@graview/core 0.1.0

package/dist/cli/check/settings.d.ts

@@ -0,0 +1,16 @@
+import type { AnySchema } from "../../schema/schema.js";
+/**
+ * `note` is a QUESTION ASKED OUT LOUD, not a problem.
+ *
+ * Some things a checker can see are legitimate designs that the author
+ * should nonetheless have looked at once: a lens written for this app and
+ * never proved against another domain, a role name two vocabularies both
+ * use, a kind unreachable on an empty graph. Filed as warnings they would
+ * be warnings that can only ever be acknowledged, and those are the ones
+ * people learn to scroll past — which costs the checker its authority on
+ * the warnings that matter. So they have their own voice: counted, printed,
+ * and never a failure.
+ */
+import type { CheckContext } from "./context.js";
+export declare function checkSettings<S extends AnySchema>(ctx: CheckContext<S>): void;
+//# sourceMappingURL=settings.d.ts.map

package/dist/cli/check/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../src/cli/check/settings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,wBAAgB,aAAa,CAAC,CAAC,SAAS,SAAS,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CA8E7E"}

package/dist/cli/check/settings.js

@@ -0,0 +1,81 @@
+export function checkSettings(ctx) {
+    const { app, add } = ctx;
+    /*
+     * A SETTING NOBODY CAN HONOUR IS A CONTROL THAT DOES NOTHING.
+     *
+     * The profile pane draws what the app declares, and the shell knows
+     * exactly two ways to carry an answer to every surface. A setting with
+     * one option is not a setting; one whose starting value is not among its
+     * options opens on an answer nobody chose and cannot choose again; two
+     * settings with one name write over each other's storage.
+     */
+    const settingNames = new Set();
+    const HONOURED = ["root-font-size", "root-attribute"];
+    for (const setting of app.settings ?? []) {
+        const where = `settings["${setting.name}"]`;
+        if (!/^[a-z][a-z0-9-]*$/.test(setting.name)) {
+            add({
+                severity: "error",
+                code: "setting-name-unusable",
+                where,
+                message: `"${setting.name}" becomes a storage key and a data-graview- attribute, so it must be kebab-case.`,
+                fix: `Rename it to lower-case letters, digits and hyphens — "text-size", not "${setting.name}".`,
+            });
+        }
+        if (settingNames.has(setting.name)) {
+            add({
+                severity: "error",
+                code: "setting-name-taken",
+                where,
+                message: `Two settings are called "${setting.name}"; they would write over each other.`,
+                fix: `Give one of them another name.`,
+            });
+        }
+        settingNames.add(setting.name);
+        if (!HONOURED.includes(setting.honoured)) {
+            add({
+                severity: "error",
+                code: "setting-not-honourable",
+                where: `${where}.honoured`,
+                message: `Nothing knows how to apply "${setting.honoured}", so this control would do nothing.`,
+                fix: `Use ${HONOURED.map((one) => `"${one}"`).join(" or ")}.`,
+            });
+        }
+        if (setting.options.length < 2) {
+            add({
+                severity: "error",
+                code: "setting-without-a-choice",
+                where: `${where}.options`,
+                message: `A setting with ${setting.options.length === 0 ? "no" : "one"} option is not something a person can set.`,
+                fix: `Declare at least two options, or drop the setting.`,
+            });
+        }
+        if (!setting.options.some((option) => option.value === setting.initial)) {
+            add({
+                severity: "error",
+                code: "setting-starts-nowhere",
+                where: `${where}.initial`,
+                message: `It opens on "${setting.initial}", which is not one of its options — nobody could choose it back.`,
+                fix: `Set initial to one of: ${setting.options.map((option) => `"${option.value}"`).join(", ")}.`,
+            });
+        }
+        if (setting.honoured === "root-font-size") {
+            for (const option of setting.options) {
+                // The starting option means "leave it as the reader has it" and
+                // stamps nothing, so it is a word rather than a length.
+                if (option.value === setting.initial)
+                    continue;
+                if (!/^[0-9.]+(px|rem|em|%|pt)$/.test(option.value)) {
+                    add({
+                        severity: "error",
+                        code: "setting-not-a-length",
+                        where: `${where}.options["${option.value}"]`,
+                        message: `A root font size has to be a CSS length; "${option.value}" is not one.`,
+                        fix: `Use a length with a unit, such as "18px".`,
+                    });
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=settings.js.map

package/dist/cli/check/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../../src/cli/check/settings.ts"],"names":[],"mappings":"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"}

package/dist/cli/check.d.ts

@@ -0,0 +1,36 @@
+import type { GraviewApp } from "../app.js";
+import type { AnySchema } from "../schema/schema.js";
+export type Severity = "error" | "warning" | "note";
+export interface Finding {
+    readonly severity: Severity;
+    readonly code: string;
+    /** Where the problem is, in terms an agent can act on. */
+    readonly where: string;
+    readonly message: string;
+    /** The concrete edit that would fix it. */
+    readonly fix: string;
+}
+export interface CheckResult {
+    readonly app: string;
+    readonly findings: readonly Finding[];
+    readonly errors: number;
+    readonly warnings: number;
+    /** Questions asked out loud: never a failure, always worth one read. */
+    readonly notes: number;
+    readonly ok: boolean;
+}
+/**
+ * The build-time safety net. Most of these mistakes are already typecheck
+ * failures — an edge to an undeclared kind, a view for a kind nobody
+ * declared — but a schema assembled dynamically, or an app mid-rename, can
+ * slip past `tsc`. Every message names the file-level thing to change,
+ * because the primary reader is an agent editing the declaration.
+ */
+/**
+ * EVERY QUESTION A DECLARATION IS ASKED, in the order it is asked. Each
+ * family of checks lives in `check/` and is handed the same context; the
+ * order is the report's order, which is the order a person reads it in.
+ */
+export declare function checkApp<S extends AnySchema>(app: GraviewApp<S>): CheckResult;
+export declare function formatFindings(result: CheckResult): string;
+//# sourceMappingURL=check.d.ts.map

package/dist/cli/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/cli/check.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAsCrD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;GAMG;AAEH;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,SAAS,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,WAAW,CAsC7E;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAiB1D"}

package/dist/cli/check.js

@@ -0,0 +1,76 @@
+import { deriveEditMutations, deriveRemoveMutations } from "../mutations/derive-edits.js";
+/**
+ * `note` is a QUESTION ASKED OUT LOUD, not a problem.
+ *
+ * Some things a checker can see are legitimate designs that the author
+ * should nonetheless have looked at once: a lens written for this app and
+ * never proved against another domain, a role name two vocabularies both
+ * use, a kind unreachable on an empty graph. Filed as warnings they would
+ * be warnings that can only ever be acknowledged, and those are the ones
+ * people learn to scroll past — which costs the checker its authority on
+ * the warnings that matter. So they have their own voice: counted, printed,
+ * and never a failure.
+ */
+import { checkAccents, checkActsFromEnds, checkBlankInstallation, checkEditableFields, checkFigures, checkLensBindings, checkMigrations, checkModelWritten, checkModules, checkPalette, checkPlots, checkPolicy, checkProviders, checkReadings, checkEdgeNamesAgree, checkRoutes, checkSettings, checkShippedLenses, checkUnmakeable, checkArrangement, } from "./check/index.js";
+/**
+ * The build-time safety net. Most of these mistakes are already typecheck
+ * failures — an edge to an undeclared kind, a view for a kind nobody
+ * declared — but a schema assembled dynamically, or an app mid-rename, can
+ * slip past `tsc`. Every message names the file-level thing to change,
+ * because the primary reader is an agent editing the declaration.
+ */
+/**
+ * EVERY QUESTION A DECLARATION IS ASKED, in the order it is asked. Each
+ * family of checks lives in `check/` and is handed the same context; the
+ * order is the report's order, which is the order a person reads it in.
+ */
+export function checkApp(app) {
+    const findings = [];
+    const kinds = new Set(app.schema.kinds);
+    const declaredMutations = app.mutations ?? [];
+    const derivedEdits = deriveEditMutations(app.schema, declaredMutations);
+    const derivedRemoves = deriveRemoveMutations(app.schema, declaredMutations);
+    // Declared and derived: a grant may name `edit-<kind>` or `remove-<kind>`, and a repair may too.
+    const mutations = new Map([...declaredMutations, ...derivedEdits, ...derivedRemoves].map((m) => [m.name, m]));
+    const invariants = new Map((app.invariants ?? []).map((i) => [i.name, i]));
+    const add = (f) => findings.push(f);
+    const ctx = { app, kinds, declaredMutations, derivedEdits, derivedRemoves, mutations, invariants, add };
+    checkRoutes(ctx);
+    checkShippedLenses(ctx);
+    checkBlankInstallation(ctx);
+    checkProviders(ctx);
+    checkPlots(ctx);
+    checkFigures(ctx);
+    const writtenByAModel = checkModelWritten(ctx);
+    checkSettings(ctx);
+    checkMigrations(ctx);
+    checkAccents(ctx);
+    checkModules(ctx);
+    checkReadings(ctx);
+    checkEdgeNamesAgree(ctx);
+    checkActsFromEnds(ctx, writtenByAModel);
+    checkUnmakeable(ctx);
+    checkEditableFields(ctx);
+    checkPolicy(ctx);
+    checkPalette(ctx);
+    checkLensBindings(ctx);
+    checkArrangement(ctx);
+    const errors = findings.filter((f) => f.severity === "error").length;
+    const notes = findings.filter((f) => f.severity === "note").length;
+    const warnings = findings.length - errors - notes;
+    return { app: app.name, findings, errors, warnings, notes, ok: errors === 0 };
+}
+export function formatFindings(result) {
+    if (result.findings.length === 0) {
+        return `graview check: ${result.app} — no problems found.`;
+    }
+    const said = { error: "ERROR", warning: "warn ", note: "note " };
+    const lines = result.findings.map((f) => `${said[f.severity]} [${f.code}] ${f.where}\n` +
+        `        ${f.message}\n        fix: ${f.fix}`);
+    return [
+        `graview check: ${result.app}`,
+        ...lines,
+        `${result.errors} error(s), ${result.warnings} warning(s)${result.notes > 0 ? `, ${result.notes} note(s)` : ""}`,
+    ].join("\n");
+}
+//# sourceMappingURL=check.js.map

package/dist/cli/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/cli/check.ts"],"names":[],"mappings":"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"}

package/dist/cli/create.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `graview create <dir>`: a product on Graview, started.
+ *
+ * The generator (`../scaffold`) decides what a project is; this decides
+ * what touching a real filesystem should look like — refusing to write into
+ * a directory that already has things in it, installing with the package
+ * manager the person is evidently using, and saying what to do next rather
+ * than printing a file list.
+ */
+export declare const CREATE_USAGE = "  graview create <dir> [--name \"Field Notes\"] [--kind note] [--plural notes]\n      Starts a product on Graview in <dir>: the declaration split into domain\n      and UI, an eighty-line shell, a headless test, a CI workflow.\n        --name <text>      the product's name (default: from <dir>)\n        --kind <slug>      the first node kind (default: item)\n        --plural <slug>    its plural (default: <kind>s)\n        --link <path>      consume the framework from a sibling checkout by\n                           path rather than from a registry\n        --pm pnpm|npm      the package manager (default: whichever ran this)\n        --port <n>         the dev server port (default: 5170)\n        --accent <#hex>    the brand accent (default: a worked green)\n        --no-install       write the files and stop\n        --no-skills        do not install the authoring skills\n        --no-git           do not initialise a git repository\n        --workspace        the layout every real product ends up with: a\n                           workspace root with the app under app/ and the\n                           harness scripts at the root\n        --merge            write only the files that do not exist yet, and\n                           name every collision without touching it\n        --force            write into a directory that is not empty\n";
+export interface CreateIo {
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+    /** Runs a command in a directory and reports whether it succeeded. */
+    readonly run: (command: string, args: readonly string[], cwd: string) => boolean;
+}
+/** pnpm when it ran this (`pnpm create graview`, `pnpm dlx`), else npm. */
+export declare function packageManagerFromEnv(env?: NodeJS.ProcessEnv): "pnpm" | "npm";
+export declare function create(argv: readonly string[], io?: CreateIo): Promise<number>;
+//# sourceMappingURL=create.d.ts.map

package/dist/cli/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/cli/create.ts"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AAEH,eAAO,MAAM,YAAY,81CAoBxB,CAAC;AAEF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CAClF;AAgBD,2EAA2E;AAC3E,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,KAAK,CAG1F;AAkBD,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,GAAE,QAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6K/F"}

package/dist/cli/create.js

@@ -0,0 +1,251 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { LINKED_PACKAGES, scaffoldProject, validateScaffoldOptions } from "../scaffold/index.js";
+/**
+ * `graview create <dir>`: a product on Graview, started.
+ *
+ * The generator (`../scaffold`) decides what a project is; this decides
+ * what touching a real filesystem should look like — refusing to write into
+ * a directory that already has things in it, installing with the package
+ * manager the person is evidently using, and saying what to do next rather
+ * than printing a file list.
+ */
+export const CREATE_USAGE = `  graview create <dir> [--name "Field Notes"] [--kind note] [--plural notes]
+      Starts a product on Graview in <dir>: the declaration split into domain
+      and UI, an eighty-line shell, a headless test, a CI workflow.
+        --name <text>      the product's name (default: from <dir>)
+        --kind <slug>      the first node kind (default: item)
+        --plural <slug>    its plural (default: <kind>s)
+        --link <path>      consume the framework from a sibling checkout by
+                           path rather than from a registry
+        --pm pnpm|npm      the package manager (default: whichever ran this)
+        --port <n>         the dev server port (default: 5170)
+        --accent <#hex>    the brand accent (default: a worked green)
+        --no-install       write the files and stop
+        --no-skills        do not install the authoring skills
+        --no-git           do not initialise a git repository
+        --workspace        the layout every real product ends up with: a
+                           workspace root with the app under app/ and the
+                           harness scripts at the root
+        --merge            write only the files that do not exist yet, and
+                           name every collision without touching it
+        --force            write into a directory that is not empty
+`;
+const defaultIo = {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+    run: (command, args, cwd) => spawnSync(command, [...args], { cwd, stdio: "inherit", shell: process.platform === "win32" }).status === 0,
+};
+function flag(argv, name) {
+    const index = argv.indexOf(name);
+    if (index === -1)
+        return undefined;
+    const value = argv[index + 1];
+    return value === undefined || value.startsWith("--") ? "" : value;
+}
+/** pnpm when it ran this (`pnpm create graview`, `pnpm dlx`), else npm. */
+export function packageManagerFromEnv(env = process.env) {
+    const agent = env["npm_config_user_agent"] ?? "";
+    return agent.startsWith("pnpm") ? "pnpm" : "npm";
+}
+/**
+ * The core that is running: its version, so a project pins what made it.
+ * Every @graview/* package and the `graview` tool share one version (a
+ * changesets fixed group), so `^<this>` names a version of each that exists.
+ */
+function ownManifest() {
+    try {
+        const manifest = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), "../../package.json"), "utf8"));
+        return { version: manifest.version ?? "0.0.0" };
+    }
+    catch {
+        return { version: "0.0.0" };
+    }
+}
+export async function create(argv, io = defaultIo) {
+    const dir = argv.find((arg, index) => !arg.startsWith("--") && (index === 0 || !argv[index - 1].startsWith("--")));
+    if (!dir) {
+        io.stderr(`graview create: a directory is required\n\n${CREATE_USAGE}`);
+        return 2;
+    }
+    const asked = resolve(process.cwd(), dir);
+    const force = argv.includes("--force");
+    /*
+     * A DIRECTORY THAT ALREADY EXISTS IS THE NORMAL CASE.
+     *
+     * The realistic start is a repository somebody has already made: a README
+     * they wrote, a licence, CI, assistant instruction files from some other
+     * tool. `--force` is too blunt for that — it writes over the README — so
+     * two products independently worked around it by scaffolding into `app/`
+     * and hand-writing a workspace root, which is a scaffolder gap rather
+     * than a taste they shared.
+     *
+     * `--merge` writes only what is not there, names every collision without
+     * touching it, and exits non-zero so a script cannot mistake a partial
+     * write for a clean one. `--force` keeps its meaning exactly.
+     */
+    const merge = argv.includes("--merge");
+    if (existsSync(asked) && readdirSync(asked).length > 0 && !force && !merge) {
+        io.stderr(`graview create: ${dir} is not empty. Pass --merge to write only what is missing, or --force to write into it anyway.\n`);
+        return 2;
+    }
+    const { version } = ownManifest();
+    const pmFlag = flag(argv, "--pm");
+    const packageManager = pmFlag === "pnpm" || pmFlag === "npm" ? pmFlag : packageManagerFromEnv();
+    const portFlag = flag(argv, "--port");
+    const linkFlag = flag(argv, "--link");
+    // Everything that can be refused is refused before a directory exists.
+    const base = {
+        name: flag(argv, "--name") || fromDirectoryName(dir),
+        ...(flag(argv, "--kind") ? { kind: flag(argv, "--kind") } : {}),
+        // "Shifts" is what a person types; the slug is what the generator wants.
+        ...(flag(argv, "--plural") ? { plural: flag(argv, "--plural").trim().toLowerCase() } : {}),
+        ...(flag(argv, "--accent") ? { accent: flag(argv, "--accent") } : {}),
+        ...(portFlag ? { port: Number(portFlag) } : {}),
+        packageManager,
+        ...(argv.includes("--workspace") ? { workspace: true } : {}),
+        range: `^${version}`,
+    };
+    const problems = [...validateScaffoldOptions(base)];
+    if (linkFlag !== undefined && linkFlag !== "") {
+        const checkout = resolve(process.cwd(), linkFlag);
+        if (!existsSync(resolve(checkout, "packages/core"))) {
+            problems.push(`--link ${linkFlag} is not a framework checkout: no packages/core in it`);
+        }
+        else {
+            // A linked project resolves every type from the framework's dist, so
+            // an unbuilt framework fails later, in tsc, one package at a time.
+            const unbuilt = LINKED_PACKAGES.filter((pkg) => !existsSync(resolve(checkout, "packages", pkg, "dist/index.js")));
+            if (unbuilt.length > 0) {
+                problems.push(`the framework at ${linkFlag} is not built (no dist in ${unbuilt.join(", ")}). Run: pnpm -C ${linkFlag} install && pnpm -C ${linkFlag} build`);
+            }
+        }
+    }
+    if (problems.length > 0) {
+        io.stderr(`graview create: ${problems.join("\ngraview create: ")}\n`);
+        return 2;
+    }
+    /*
+     * Relative paths are computed from where the project REALLY is. A temp
+     * directory on macOS is reached through a symlink, and a `link:` written
+     * from the unresolved path is one level short of the framework once pnpm
+     * resolves the project — a dangling symlink, and no error until tsc.
+     */
+    mkdirSync(asked, { recursive: true });
+    const target = realpathSync(asked);
+    const framework = linkFlag !== undefined && linkFlag !== "" ? realpathSync(resolve(process.cwd(), linkFlag)) : undefined;
+    const link = framework !== undefined ? toPosix(relative(target, framework)) : undefined;
+    if (framework !== undefined && !relative(framework, target).startsWith("..")) {
+        io.stderr(`graview create: ${dir} is inside the framework checkout, so it will land in the framework's git history. A product lives in its own repository beside it — e.g. ${toPosix(relative(process.cwd(), resolve(framework, "..", dir.split(/[\\/]/).pop() ?? dir)))}.\n`);
+    }
+    const frameworkRepo = framework !== undefined ? originSlug(framework) : undefined;
+    const options = {
+        ...base,
+        ...(link !== undefined ? { link } : {}),
+        ...(frameworkRepo ? { frameworkRepo } : {}),
+    };
+    const scaffold = scaffoldProject(options);
+    const collisions = [];
+    let written = 0;
+    for (const file of scaffold.files) {
+        const path = resolve(target, file.path);
+        if (merge && existsSync(path)) {
+            collisions.push(file.path);
+            continue;
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, file.contents, "utf8");
+        written += 1;
+    }
+    io.stdout(`graview create: ${written} files → ${dir}\n`);
+    const install = !argv.includes("--no-install");
+    const skills = !argv.includes("--no-skills");
+    const pm = scaffold.packageManager;
+    const run = pm === "pnpm" ? "pnpm" : "npm run";
+    // A repository, because the CI workflow just written assumes one — unless
+    // this directory is already inside one, which is the person's own choice.
+    let initialised = false;
+    if (!argv.includes("--no-git") && !insideGitRepo(target)) {
+        initialised = io.run("git", ["init", "--quiet"], target);
+    }
+    if (install) {
+        io.stdout(`graview create: ${pm} install\n`);
+        if (!io.run(pm, ["install"], target)) {
+            io.stderr(`graview create: ${pm} install failed. The files are in place; install by hand and run \`${run} verify\`.\n`);
+            return 1;
+        }
+        if (skills) {
+            const bin = resolve(target, "node_modules/.bin/graview");
+            if (existsSync(bin)) {
+                io.run(bin, ["skills", "install", "."], target);
+            }
+            else {
+                io.stderr("graview create: graview did not install, so the authoring skills were not written.\n");
+            }
+        }
+    }
+    else if (skills) {
+        /*
+         * THE SKILLS COME THROUGH THE PACKAGE MANAGER, so `--no-install` skips
+         * them too — and it used to skip them SILENTLY, which is the expensive
+         * half: an agent starts on a fresh product without the skills that teach
+         * it how, which is the single highest-leverage thing the framework
+         * ships, and nothing on the screen said they were missing.
+         */
+        io.stdout(`graview create: skills: skipped (needs install — then \`${run} skills\`)\n`);
+    }
+    io.stdout(`\n${scaffold.name} is a product on Graview. Its first kind is "${scaffold.kind}".\n\n` +
+        `  cd ${dir}\n` +
+        (install ? "" : `  ${pm} install\n`) +
+        `  ${run} dev        # http://localhost:${scaffold.port}  (/pages is the routed face)\n` +
+        `  ${run} verify     # typecheck, tests, build, graview check\n` +
+        (initialised ? `  git add -A && git commit -m "${scaffold.name}, on Graview"\n` : "") +
+        "\n" +
+        (scaffold.linked
+            ? `The framework is consumed by path from ${link}: rebuild it (pnpm -C ${link} build) when its sources change.\n` +
+                `Its CI checks the framework out beside the app${frameworkRepo ? ` from ${frameworkRepo}` : " — fill in the repository in .github/workflows/ci.yml"}; a private framework needs a FRAMEWORK_TOKEN secret.\n\n`
+            : "") +
+        `Then declare more: src/domain/ is the whole surface, and \`${run} check\` says what is wrong with it.\n`);
+    if (collisions.length > 0) {
+        io.stderr(`\ngraview create: ${collisions.length} file${collisions.length === 1 ? "" : "s"} already existed and ${collisions.length === 1 ? "was" : "were"} left exactly as ${collisions.length === 1 ? "it was" : "they were"}:\n` +
+            collisions.map((path) => `  ${path}\n`).join("") +
+            `Merge what you want from a scaffold written elsewhere, or pass --force to overwrite.\n`);
+        return 1;
+    }
+    return 0;
+}
+/** Whether a directory already sits inside a git work tree. */
+function insideGitRepo(dir) {
+    let current = dir;
+    for (;;) {
+        if (existsSync(resolve(current, ".git")))
+            return true;
+        const parent = dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
+/** The framework's GitHub "owner/name", from its origin remote, if it has one. */
+function originSlug(framework) {
+    const result = spawnSync("git", ["-C", framework, "remote", "get-url", "origin"], { encoding: "utf8" });
+    if (result.status !== 0)
+        return undefined;
+    const match = /github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\s*$/.exec(result.stdout);
+    return match?.[1];
+}
+function fromDirectoryName(dir) {
+    const base = dir.replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? dir;
+    return base
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+function toPosix(path) {
+    const posix = path.split("\\").join("/");
+    return isAbsolute(path) || posix.startsWith(".") ? posix : `./${posix}`;
+}
+//# sourceMappingURL=create.js.map

package/dist/cli/create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../src/cli/create.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxG,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,uBAAuB,EAAwB,MAAM,sBAAsB,CAAC;AAEvH;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;CAoB3B,CAAC;AASF,MAAM,SAAS,GAAa;IAC1B,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;IAC5C,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;IAC5C,GAAG,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,CAC1B,SAAS,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC;CAC7G,CAAC;AAEF,SAAS,IAAI,CAAC,IAAuB,EAAE,IAAY;IACjD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACnC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IAC9B,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AACpE,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,qBAAqB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACxE,MAAM,KAAK,GAAG,GAAG,CAAC,uBAAuB,CAAC,IAAI,EAAE,CAAC;IACjD,OAAO,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW;IAClB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,oBAAoB,CAAC,EAAE,MAAM,CAAC,CACrE,CAAC;QAC1B,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,IAAI,OAAO,EAAE,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAC9B,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAuB,EAAE,KAAe,SAAS;IAC5E,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpH,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,EAAE,CAAC,MAAM,CAAC,8CAA8C,YAAY,EAAE,CAAC,CAAC;QACxE,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACvC;;;;;;;;;;;;;OAaG;IACH,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACvC,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;QAC3E,EAAE,CAAC,MAAM,CACP,mBAAmB,GAAG,kGAAkG,CACzH,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,CAAC;IAClC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAClC,MAAM,cAAc,GAClB,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,qBAAqB,EAAE,CAAC;IAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAEtC,uEAAuE;IACvE,MAAM,IAAI,GAAoB;QAC5B,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,iBAAiB,CAAC,GAAG,CAAC;QACpD,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,yEAAyE;QACzE,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAE,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3F,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,cAAc;QACd,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,KAAK,EAAE,IAAI,OAAO,EAAE;KACrB,CAAC;IACF,MAAM,QAAQ,GAAG,CAAC,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QAC9C,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC;QAClD,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC;YACpD,QAAQ,CAAC,IAAI,CAAC,UAAU,QAAQ,sDAAsD,CAAC,CAAC;QAC1F,CAAC;aAAM,CAAC;YACN,qEAAqE;YACrE,mEAAmE;YACnE,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,CACpC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,eAAe,CAAC,CAAC,CAC1E,CAAC;YACF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvB,QAAQ,CAAC,IAAI,CACX,oBAAoB,QAAQ,6BAA6B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,QAAQ,uBAAuB,QAAQ,QAAQ,CAC9I,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,EAAE,CAAC,MAAM,CAAC,mBAAmB,QAAQ,CAAC,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC;QACtE,OAAO,CAAC,CAAC;IACX,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,SAAS,GACb,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACzG,MAAM,IAAI,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACxF,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7E,EAAE,CAAC,MAAM,CACP,mBAAmB,GAAG,6IAA6I,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,CACpQ,CAAC;IACJ,CAAC;IACD,MAAM,aAAa,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAElF,MAAM,OAAO,GAAoB;QAC/B,GAAG,IAAI;QACP,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5C,CAAC;IAEF,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,KAAK,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC,CAAC;IACf,CAAC;IACD,EAAE,CAAC,MAAM,CAAC,mBAAmB,OAAO,YAAY,GAAG,IAAI,CAAC,CAAC;IAEzD,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IAC7C,MAAM,EAAE,GAAG,QAAQ,CAAC,cAAc,CAAC;IACnC,MAAM,GAAG,GAAG,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAE/C,0EAA0E;IAC1E,0EAA0E;IAC1E,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QACzD,WAAW,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3D,CAAC;IAED,IAAI,OAAO,EAAE,CAAC;QACZ,EAAE,CAAC,MAAM,CAAC,mBAAmB,EAAE,YAAY,CAAC,CAAC;QAC7C,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC;YACrC,EAAE,CAAC,MAAM,CAAC,mBAAmB,EAAE,sEAAsE,GAAG,cAAc,CAAC,CAAC;YACxH,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC;YACzD,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpB,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;YAClD,CAAC;iBAAM,CAAC;gBACN,EAAE,CAAC,MAAM,CAAC,sFAAsF,CAAC,CAAC;YACpG,CAAC;QACH,CAAC;IACH,CAAC;SAAM,IAAI,MAAM,EAAE,CAAC;QAClB;;;;;;WAMG;QACH,EAAE,CAAC,MAAM,CAAC,2DAA2D,GAAG,cAAc,CAAC,CAAC;IAC1F,CAAC;IAED,EAAE,CAAC,MAAM,CACP,KAAK,QAAQ,CAAC,IAAI,gDAAgD,QAAQ,CAAC,IAAI,QAAQ;QACrF,QAAQ,GAAG,IAAI;QACf,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,YAAY,CAAC;QACpC,KAAK,GAAG,kCAAkC,QAAQ,CAAC,IAAI,iCAAiC;QACxF,KAAK,GAAG,wDAAwD;QAChE,CAAC,WAAW,CAAC,CAAC,CAAC,kCAAkC,QAAQ,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC;QACrF,IAAI;QACJ,CAAC,QAAQ,CAAC,MAAM;YACd,CAAC,CAAC,0CAA0C,IAAI,yBAAyB,IAAI,oCAAoC;gBAC/G,iDAAiD,aAAa,CAAC,CAAC,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC,CAAC,uDAAuD,2DAA2D;YAChN,CAAC,CAAC,EAAE,CAAC;QACP,8DAA8D,GAAG,wCAAwC,CAC5G,CAAC;IACF,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,EAAE,CAAC,MAAM,CACP,qBAAqB,UAAU,CAAC,MAAM,QAAQ,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,wBAC9E,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MACpC,oBAAoB,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,KAAK;YACvE,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,wFAAwF,CAC3F,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,+DAA+D;AAC/D,SAAS,aAAa,CAAC,GAAW;IAChC,IAAI,OAAO,GAAG,GAAG,CAAC;IAClB,SAAS,CAAC;QACR,IAAI,UAAU,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QACtD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,MAAM,KAAK,OAAO;YAAE,OAAO,KAAK,CAAC;QACrC,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;AACH,CAAC;AAED,kFAAkF;AAClF,SAAS,UAAU,CAAC,SAAiB;IACnC,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IACxG,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,KAAK,GAAG,kDAAkD,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrF,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAW;IACpC,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,IAAI,GAAG,CAAC;IACpE,OAAO,IAAI;SACR,KAAK,CAAC,SAAS,CAAC;SAChB,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAC3D,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,SAAS,OAAO,CAAC,IAAY;IAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzC,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;AAC1E,CAAC"}

package/dist/cli/describe.d.ts

@@ -0,0 +1,35 @@
+import { type GraviewApp } from "../app.js";
+import type { AnySchema } from "../schema/schema.js";
+/**
+ * WHAT THIS APP IS, READ OUT — the rung between `check` and a browser.
+ *
+ * "Run it and look" is the sentence every skill ends on, and it is the one
+ * instruction an agent cannot follow: it can declare, and it cannot see. The
+ * product that found thirty-one things in this framework said so plainly —
+ * *"what no check caught, running it did"* — and listed four faults that
+ * passed every static check and were obvious the moment somebody opened the
+ * thing: a hue in the wrong unit, so every surface drew red; a lens built
+ * from the wrong node set, so every piece of ground drew empty; a policy
+ * declared with no principal supplied, so every act in the product was
+ * refused; a colour that was not a token, so the contrast guarantee did not
+ * apply.
+ *
+ * Every one of those is visible in a DESCRIPTION. The interface here is
+ * derived, which is exactly what makes it describable: the same derivations
+ * that draw a district, offer an act and refuse one can say what they would
+ * do, in words, with no browser and no eyes.
+ *
+ * This is deliberately not a screenshot in prose. It states the things that
+ * are wrong ON A SCREEN and invisible IN A FILE, and says nothing that
+ * `check` already says.
+ */
+export interface DescribeOptions {
+    /** A seat to answer "what can this person do" as. */
+    readonly as?: {
+        readonly kind: "human" | "agent";
+        readonly id?: string;
+        readonly roles?: readonly string[];
+    };
+}
+export declare function describeApp<S extends AnySchema>(app: GraviewApp<S>, options?: DescribeOptions): string;
+//# sourceMappingURL=describe.d.ts.map

package/dist/cli/describe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.d.ts","sourceRoot":"","sources":["../../src/cli/describe.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsC,KAAK,UAAU,EAAwC,MAAM,WAAW,CAAC;AAItH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAIrD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;CAC9G;AAoBD,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,EAC7C,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAClB,OAAO,GAAE,eAAoB,GAC5B,MAAM,CA+PR"}