@vincentt-xr/cli 0.15.2 → 0.17.0

package/dist/platform/zonePath.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The path floor: whether a path may be written into a creator's repository at
+ * all. Purpose-built, and deliberately NOT `publish/paths.ts`.
+ *
+ * The publish validator was written to bound an S3 key for a dist upload, where
+ * the worst case is a weird object name. This bounds a DESTINATION FOR AN
+ * OVERWRITE IN SOMEONE ELSE'S REPOSITORY, where the worst case is code
+ * execution. Run against the zone corpus it accepts `.git/hooks/pre-commit`,
+ * `.git/config`, `.env`, `.npmrc`, `.gitignore`,
+ * `.github/workflows/release.yml`, `node_modules/.bin/esbuild`,
+ * `pnpm-lock.yaml` — and `src/Scene.tsx`, the one file the entire safety
+ * argument names. It rejects only `../` and `.`-segments and normalizes no
+ * unicode, so an RTL override, a Cyrillic homoglyph and a division slash all
+ * pass. Its `validatePathSet` also hard-requires `index.html`, so it FAILS the
+ * legitimate zone set — a reuse would have gone red on the happy path and the
+ * cheapest fix would have been to drop the control while the record still
+ * claimed it.
+ *
+ * THE MANIFEST IS NEVER CONSULTED HERE. It decides which of the two zones a
+ * PERMISSIBLE path belongs to; it is never the authority for whether a path is
+ * permissible. A boundary with no floor under it is not a boundary — it is a
+ * suggestion the manifest could withdraw. So this code is identical for every
+ * template version and runs BEFORE the manifest is read.
+ */
+/** The closed reason enum. Every refusal names the rule that fired. */
+export type ZonePathRejection = "non_ascii" | "denied_by_name" | "malformed" | "dot_segment" | "node_modules" | "top_level" | "extension" | "too_deep" | "too_long" | "duplicate" | "case_duplicate" | "in_both_zones";
+export interface ZonePathError {
+    rule: ZonePathRejection;
+    path: string;
+}
+export type ZonePathResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+} & ZonePathError;
+/**
+ * Rule 2 — denied by name, checked BEFORE any zone lookup.
+ *
+ * `src/Scene.tsx` is the creator's surface and the file the whole safety
+ * argument rests on. It is the ONLY entry here that needs rule 2 to survive:
+ * it passes every other rule (a `src/` path with an allowed extension), so
+ * without this list a manifest listing it under `platform` would be obeyed. The
+ * grounding contracts are the creator's own agent contract and are additionally
+ * refused by rules 6 and 7 — they are named here so rule 2 is the rule that
+ * fires for them, which is what the corpus asserts.
+ *
+ * A manifest listing any of these under `platform` is REFUSED rather than
+ * obeyed. That is why this cannot be expressed as "not in the creator list":
+ * the manifest is the thing being distrusted.
+ *
+ * ONLY `src/Scene.tsx` IS NAMED HERE, and the three grounding contracts are
+ * deliberately absent — not weakened, ALREADY REFUSED, twice, before this rule
+ * is consulted. Each is a single-segment root path, and rule 6 admits a
+ * single-segment path only if it is in ALLOWED_ROOT_FILES, which none of them is;
+ * rule 7's extension allowlist refuses `.md` again. Naming them would therefore
+ * add no refusal, while putting a vendor-specific agent filename into CLI source
+ * — which f12 tripwire (a) sweeps for absolutely, because the platform must never
+ * be able to tell which agent is driving it. A name assembled from fragments to
+ * satisfy both would be worse than either: the source would no longer contain a
+ * string the next reader can grep, so the code would lie about what it refuses.
+ *
+ * `src/Scene.tsx` genuinely needs this rule: it is a two-segment path under `src`,
+ * so rules 6 and 7 both ADMIT it, and only a deny-by-name stops a manifest that
+ * lists the creator's own file as a write target. It is also the one file the
+ * whole safety argument rests on.
+ *
+ * NOTHING HERE BRANCHES on which of these files exists, which is the property
+ * the tripwire actually protects.
+ */
+export declare const DENIED_BY_NAME: readonly string[];
+/**
+ * Rule 2's predicate, CASE-INSENSITIVE, exported so the floor and the write site
+ * cannot drift.
+ *
+ * An exact match was a hole, and it was the worst available hole: `src/scene.tsx`
+ * passed every rule, and on a case-insensitive filesystem (macOS default,
+ * Windows) the write RESOLVED ONTO the creator's `src/Scene.tsx` — destroying the
+ * one file the entire safety argument rests on, with no backup, no pre-flight
+ * check and no revert, all ruled out deliberately. Worse, the report then named
+ * the destroyed file under LEFT ALONE while filing the destruction as a clean
+ * replacement, so the only compensating control pointed away from the damage.
+ *
+ * Case is the ASCII member of rule 1's family: the reason unicode is normalized
+ * is that a path can render as one file and BE another, defeating the human
+ * review of the manifest diff, which is the last control once the mechanical ones
+ * are gone. A case-only spelling does exactly that in plain ASCII.
+ *
+ * Case-insensitive is correct on a case-SENSITIVE filesystem too: there, a
+ * manifest naming a case-variant of the creator's surface creates a second file
+ * shadowing theirs, which is hostile for a different reason.
+ */
+export declare function isDeniedByName(path: string): boolean;
+/**
+ * Rule 6 — the top-level allowlist for a single-segment path.
+ *
+ * Refusal by name-absence rather than by a rule enumerating every hazard, so a
+ * file class nobody predicted (`pnpm-lock.yaml`, a `Makefile`, a `Dockerfile`)
+ * is refused without anyone having thought of it.
+ *
+ * `.eslintrc.json` is DELIBERATELY ABSENT even though the template ships it and
+ * the record's example manifest lists it under `platform`. Rule 4 refuses every
+ * dot-leading segment and runs first, so an entry here would be unreachable —
+ * and rule 4 is the arm that kills `.env`, `.npmrc`, `.gitignore` and
+ * `.github/…`. Admitting one dotfile means either narrowing rule 4 or carrying a
+ * per-name exception through the floor, and both weaken the control that exists
+ * because a dotfile overwrite is the credential-adjacent case. The consequence
+ * is that `.eslintrc.json` joins `scripts/*.mjs` in the reported-not-upgraded
+ * set. Raised as a fork against the record's §5 example rather than resolved by
+ * widening the floor.
+ */
+export declare const ALLOWED_ROOT_FILES: readonly string[];
+/** Rule 6 — the only directories a multi-segment path may start in. */
+export declare const ALLOWED_TOP_DIRS: readonly string[];
+/** Rule 7 — the extension allowlist. Closes `.yaml`, `.yml`, `.sh`, extensionless. */
+export declare const ALLOWED_EXTENSIONS: readonly string[];
+/**
+ * Validate ONE path against rules 1-8. Rule 9 is set-level and lives in
+ * `validateZoneSet`.
+ *
+ * The order is load-bearing in one place and one place only: rule 2 runs before
+ * anything that could consult a zone. An innocuous-looking reorder that looks
+ * up the zone first and denies after is the regression this ordering exists to
+ * prevent, and it is invisible in a diff.
+ */
+export declare function validateZonePath(raw: string): ZonePathResult;
+/**
+ * The same floor, told which zone the entry was listed in.
+ *
+ * Rule 2 applies to the OVERWRITE zone. `src/Scene.tsx` listed under `creator`
+ * is the correct and required content of a legitimate manifest — `creator` is
+ * the never-written list, so a denied name there is the manifest agreeing with
+ * the floor rather than attacking it. Applying rule 2 to both arrays refuses the
+ * legitimate zone set, which is the same shape of defect as the publish
+ * validator's `index.html` requirement: a control that fails the happy path gets
+ * dropped under build pressure while the record still claims it exists.
+ *
+ * Rules 1 and 3-8 apply to BOTH zones, because they bound what a manifest may
+ * NAME at all, and an unlisted-but-named path is still a path this code reads.
+ */
+export declare function validateZonePathIn(raw: string, zone: "platform" | "creator"): ZonePathResult;
+export interface ZoneSet {
+    platform: string[];
+    creator: string[];
+}
+/**
+ * Rule 9 — the set level. ONE failure refuses the WHOLE manifest.
+ *
+ * A per-entry skip looks like robustness and is the smuggling path: it is
+ * exactly how one hostile entry rides in behind twenty good ones, and the twenty
+ * good writes are what make the report look normal. There is no partial accept
+ * and no `continue` in this function.
+ */
+export declare function validateZoneSet(set: ZoneSet): ZonePathError | undefined;

package/dist/platform/zonePath.js

@@ -0,0 +1,286 @@
+/**
+ * The path floor: whether a path may be written into a creator's repository at
+ * all. Purpose-built, and deliberately NOT `publish/paths.ts`.
+ *
+ * The publish validator was written to bound an S3 key for a dist upload, where
+ * the worst case is a weird object name. This bounds a DESTINATION FOR AN
+ * OVERWRITE IN SOMEONE ELSE'S REPOSITORY, where the worst case is code
+ * execution. Run against the zone corpus it accepts `.git/hooks/pre-commit`,
+ * `.git/config`, `.env`, `.npmrc`, `.gitignore`,
+ * `.github/workflows/release.yml`, `node_modules/.bin/esbuild`,
+ * `pnpm-lock.yaml` — and `src/Scene.tsx`, the one file the entire safety
+ * argument names. It rejects only `../` and `.`-segments and normalizes no
+ * unicode, so an RTL override, a Cyrillic homoglyph and a division slash all
+ * pass. Its `validatePathSet` also hard-requires `index.html`, so it FAILS the
+ * legitimate zone set — a reuse would have gone red on the happy path and the
+ * cheapest fix would have been to drop the control while the record still
+ * claimed it.
+ *
+ * THE MANIFEST IS NEVER CONSULTED HERE. It decides which of the two zones a
+ * PERMISSIBLE path belongs to; it is never the authority for whether a path is
+ * permissible. A boundary with no floor under it is not a boundary — it is a
+ * suggestion the manifest could withdraw. So this code is identical for every
+ * template version and runs BEFORE the manifest is read.
+ */
+/**
+ * Rule 2 — denied by name, checked BEFORE any zone lookup.
+ *
+ * `src/Scene.tsx` is the creator's surface and the file the whole safety
+ * argument rests on. It is the ONLY entry here that needs rule 2 to survive:
+ * it passes every other rule (a `src/` path with an allowed extension), so
+ * without this list a manifest listing it under `platform` would be obeyed. The
+ * grounding contracts are the creator's own agent contract and are additionally
+ * refused by rules 6 and 7 — they are named here so rule 2 is the rule that
+ * fires for them, which is what the corpus asserts.
+ *
+ * A manifest listing any of these under `platform` is REFUSED rather than
+ * obeyed. That is why this cannot be expressed as "not in the creator list":
+ * the manifest is the thing being distrusted.
+ *
+ * ONLY `src/Scene.tsx` IS NAMED HERE, and the three grounding contracts are
+ * deliberately absent — not weakened, ALREADY REFUSED, twice, before this rule
+ * is consulted. Each is a single-segment root path, and rule 6 admits a
+ * single-segment path only if it is in ALLOWED_ROOT_FILES, which none of them is;
+ * rule 7's extension allowlist refuses `.md` again. Naming them would therefore
+ * add no refusal, while putting a vendor-specific agent filename into CLI source
+ * — which f12 tripwire (a) sweeps for absolutely, because the platform must never
+ * be able to tell which agent is driving it. A name assembled from fragments to
+ * satisfy both would be worse than either: the source would no longer contain a
+ * string the next reader can grep, so the code would lie about what it refuses.
+ *
+ * `src/Scene.tsx` genuinely needs this rule: it is a two-segment path under `src`,
+ * so rules 6 and 7 both ADMIT it, and only a deny-by-name stops a manifest that
+ * lists the creator's own file as a write target. It is also the one file the
+ * whole safety argument rests on.
+ *
+ * NOTHING HERE BRANCHES on which of these files exists, which is the property
+ * the tripwire actually protects.
+ */
+export const DENIED_BY_NAME = Object.freeze(["src/Scene.tsx"]);
+/**
+ * Rule 2's predicate, CASE-INSENSITIVE, exported so the floor and the write site
+ * cannot drift.
+ *
+ * An exact match was a hole, and it was the worst available hole: `src/scene.tsx`
+ * passed every rule, and on a case-insensitive filesystem (macOS default,
+ * Windows) the write RESOLVED ONTO the creator's `src/Scene.tsx` — destroying the
+ * one file the entire safety argument rests on, with no backup, no pre-flight
+ * check and no revert, all ruled out deliberately. Worse, the report then named
+ * the destroyed file under LEFT ALONE while filing the destruction as a clean
+ * replacement, so the only compensating control pointed away from the damage.
+ *
+ * Case is the ASCII member of rule 1's family: the reason unicode is normalized
+ * is that a path can render as one file and BE another, defeating the human
+ * review of the manifest diff, which is the last control once the mechanical ones
+ * are gone. A case-only spelling does exactly that in plain ASCII.
+ *
+ * Case-insensitive is correct on a case-SENSITIVE filesystem too: there, a
+ * manifest naming a case-variant of the creator's surface creates a second file
+ * shadowing theirs, which is hostile for a different reason.
+ */
+export function isDeniedByName(path) {
+    const lowered = path.toLowerCase();
+    return DENIED_BY_NAME.some((denied) => denied.toLowerCase() === lowered);
+}
+/**
+ * Rule 6 — the top-level allowlist for a single-segment path.
+ *
+ * Refusal by name-absence rather than by a rule enumerating every hazard, so a
+ * file class nobody predicted (`pnpm-lock.yaml`, a `Makefile`, a `Dockerfile`)
+ * is refused without anyone having thought of it.
+ *
+ * `.eslintrc.json` is DELIBERATELY ABSENT even though the template ships it and
+ * the record's example manifest lists it under `platform`. Rule 4 refuses every
+ * dot-leading segment and runs first, so an entry here would be unreachable —
+ * and rule 4 is the arm that kills `.env`, `.npmrc`, `.gitignore` and
+ * `.github/…`. Admitting one dotfile means either narrowing rule 4 or carrying a
+ * per-name exception through the floor, and both weaken the control that exists
+ * because a dotfile overwrite is the credential-adjacent case. The consequence
+ * is that `.eslintrc.json` joins `scripts/*.mjs` in the reported-not-upgraded
+ * set. Raised as a fork against the record's §5 example rather than resolved by
+ * widening the floor.
+ */
+export const ALLOWED_ROOT_FILES = Object.freeze([
+    "index.html",
+    "package.json",
+    "tsconfig.json",
+    "tsconfig.node.json",
+    "vitest.config.ts",
+    "esbuild.config.mjs",
+]);
+/** Rule 6 — the only directories a multi-segment path may start in. */
+export const ALLOWED_TOP_DIRS = Object.freeze(["src", "public"]);
+/** Rule 7 — the extension allowlist. Closes `.yaml`, `.yml`, `.sh`, extensionless. */
+export const ALLOWED_EXTENSIONS = Object.freeze([
+    ".tsx",
+    ".ts",
+    ".css",
+    ".mjs",
+    ".json",
+    ".html",
+    ".d.ts",
+]);
+const MAX_SEGMENTS = 4;
+const MAX_PATH_BYTES = 256;
+const NON_ASCII = /[^\x20-\x7e]/;
+const DRIVE_LETTER = /^[a-zA-Z]:/;
+const CONTROL_BYTES = /[\x00-\x1f\x7f-\x9f]/;
+const SURROGATE = /[\ud800-\udfff]/;
+/**
+ * Validate ONE path against rules 1-8. Rule 9 is set-level and lives in
+ * `validateZoneSet`.
+ *
+ * The order is load-bearing in one place and one place only: rule 2 runs before
+ * anything that could consult a zone. An innocuous-looking reorder that looks
+ * up the zone first and denies after is the regression this ordering exists to
+ * prevent, and it is invisible in a diff.
+ */
+export function validateZonePath(raw) {
+    return validateZonePathIn(raw, "platform");
+}
+/**
+ * The same floor, told which zone the entry was listed in.
+ *
+ * Rule 2 applies to the OVERWRITE zone. `src/Scene.tsx` listed under `creator`
+ * is the correct and required content of a legitimate manifest — `creator` is
+ * the never-written list, so a denied name there is the manifest agreeing with
+ * the floor rather than attacking it. Applying rule 2 to both arrays refuses the
+ * legitimate zone set, which is the same shape of defect as the publish
+ * validator's `index.html` requirement: a control that fails the happy path gets
+ * dropped under build pressure while the record still claims it exists.
+ *
+ * Rules 1 and 3-8 apply to BOTH zones, because they bound what a manifest may
+ * NAME at all, and an unlisted-but-named path is still a path this code reads.
+ */
+export function validateZonePathIn(raw, zone) {
+    // Rule 1 — NFC-normalize, then reject any non-ASCII byte.
+    //
+    // Normalizing FIRST matters: a decomposed sequence and its composed form are
+    // the same file, and comparing the un-normalized string against a deny list
+    // would miss one of the two spellings. Then ASCII-only, because every hazard
+    // in this class survives every other rule: a division slash is ONE segment so
+    // no segment rule sees it, and an RTL override, a Cyrillic homoglyph and a
+    // trailing zero-width space each render as an ordinary path in a report or a
+    // manifest diff while naming a different file. That defeats the human review
+    // of the manifest diff, which is the only control left once the mechanical
+    // ones are satisfied. The template has no non-ASCII filename and never will.
+    const path = raw.normalize("NFC");
+    if (NON_ASCII.test(path))
+        return reject("non_ascii", raw);
+    // Rule 2 — denied by name. BEFORE the zone lookup, and before the cheaper
+    // structural rules, so the refusal a reader cares about is the one reported.
+    if (zone === "platform" && isDeniedByName(path)) {
+        return reject("denied_by_name", raw);
+    }
+    // Rule 3 — the arms of the publish validator that were right, restated rather
+    // than imported. Restated because importing would couple this floor to a
+    // module whose threat model is a different one, and the next edit there would
+    // silently change what may be written into a repository.
+    if (path.includes("\\"))
+        return reject("malformed", raw);
+    if (path.startsWith("/"))
+        return reject("malformed", raw);
+    if (DRIVE_LETTER.test(path))
+        return reject("malformed", raw);
+    if (path.includes("%"))
+        return reject("malformed", raw);
+    // Control bytes and lone surrogates are already excluded by rule 1 (both are
+    // outside printable ASCII); the checks stay because rule 3 is asserted by
+    // name and a future widening of rule 1 must not silently drop them.
+    if (CONTROL_BYTES.test(path))
+        return reject("malformed", raw);
+    if (SURROGATE.test(path))
+        return reject("malformed", raw);
+    // Rule 8 — length, before the split, so a pathological string is bounded
+    // before any per-segment work runs over it.
+    if (Buffer.byteLength(path, "utf8") > MAX_PATH_BYTES)
+        return reject("too_long", raw);
+    const segments = path.split("/");
+    // Rule 8 — depth.
+    if (segments.length > MAX_SEGMENTS)
+        return reject("too_deep", raw);
+    // Rule 5 — `node_modules` as a first segment. BEFORE rule 4, so the rule
+    // REPORTED for `node_modules/.bin/esbuild` is the one that names why it is
+    // dangerous (a binary the creator's next build executes) rather than the
+    // incidental dot on its second segment. Both refuse it; the attribution is
+    // what a reader and the corpus depend on, and rule 5 exists precisely because
+    // it is not redundant with rule 4.
+    if (segments[0] === "node_modules")
+        return reject("node_modules", raw);
+    // Rule 4 — the dotfile rule the publish validator has none of. `.env`,
+    // `.npmrc`, `.gitignore`, `.git/hooks/pre-commit` and `.github/…` all die
+    // here. `..` and `.` are covered by the same clause rather than separately,
+    // because "begins with a dot" is the superset and stating it once is what
+    // makes the rule hard to narrow by accident.
+    for (const seg of segments) {
+        if (seg === "")
+            return reject("dot_segment", raw);
+        if (seg.startsWith("."))
+            return reject("dot_segment", raw);
+    }
+    // Rule 6 — the top-level allowlist.
+    if (segments.length === 1) {
+        if (!ALLOWED_ROOT_FILES.includes(segments[0]))
+            return reject("top_level", raw);
+    }
+    else if (!ALLOWED_TOP_DIRS.includes(segments[0])) {
+        // `scripts/dev.mjs` is refused HERE, and that is correct and deliberate:
+        // the template's build scripts execute on the creator's machine, which is
+        // the closest thing in the template to the `node_modules/.bin` case. They
+        // move to the report's not-permitted-to-be-upgraded set rather than the
+        // allowlist being widened to admit them.
+        return reject("top_level", raw);
+    }
+    // Rule 7 — extension. `.d.ts` is checked before `.ts` would match it, but
+    // both are allowed so the order is not load-bearing; the check is a suffix
+    // test rather than a parse so `vite-env.d.ts` needs no special case.
+    if (!ALLOWED_EXTENSIONS.some((ext) => path.endsWith(ext))) {
+        return reject("extension", raw);
+    }
+    return { ok: true, path };
+}
+function reject(rule, path) {
+    return { ok: false, rule, path };
+}
+/**
+ * Rule 9 — the set level. ONE failure refuses the WHOLE manifest.
+ *
+ * A per-entry skip looks like robustness and is the smuggling path: it is
+ * exactly how one hostile entry rides in behind twenty good ones, and the twenty
+ * good writes are what make the report look normal. There is no partial accept
+ * and no `continue` in this function.
+ */
+export function validateZoneSet(set) {
+    const seen = new Set();
+    const seenLower = new Set();
+    const platform = new Set();
+    for (const zone of ["platform", "creator"]) {
+        for (const raw of set[zone]) {
+            const result = validateZonePathIn(raw, zone);
+            if (!result.ok)
+                return { rule: result.rule, path: result.path };
+            const p = result.path;
+            // Reported as in-both-zones rather than as a plain duplicate, because the
+            // two say different things to whoever fixes the manifest: a duplicate is a
+            // typo, and a path in both arrays is a file whose OWNER is contested —
+            // which either destroys creator work or leaves plumbing stale, depending
+            // on which list a reader assumes wins.
+            if (zone === "creator" && platform.has(p)) {
+                return { rule: "in_both_zones", path: p };
+            }
+            if (seen.has(p))
+                return { rule: "duplicate", path: p };
+            // A case-duplicate is two names for one file on macOS and Windows and two
+            // files on Linux, so the manifest means different things on different
+            // machines — and the overwrite set is the wrong place to discover that.
+            const lower = p.toLowerCase();
+            if (seenLower.has(lower))
+                return { rule: "case_duplicate", path: p };
+            seen.add(p);
+            seenLower.add(lower);
+            if (zone === "platform")
+                platform.add(p);
+        }
+    }
+    return undefined;
+}

package/dist/platform/zones.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `.vincentt-template.json` — the template's own per-version zone manifest.
+ *
+ * It is the authority for WHICH OF THE TWO ZONES a permissible path belongs to.
+ * It is never the authority for WHETHER a path is permissible: that is the
+ * floor, which is code, ships in the CLI, is identical for every template
+ * version, and runs BEFORE anything here consults a zone.
+ *
+ * Per-version because a project scaffolded from 1.2.0 needs 1.2.0's set, and
+ * only the 1.2.0 tag authoritatively knows it. Enumerated arrays with no globs,
+ * because the default must be LEAVE ALONE — an implicit rule claims every file
+ * the creator ever added, including one named `Scene2.tsx`, and the day a
+ * template file ships unclassified the default becomes destroy the creator's
+ * work.
+ *
+ * AN UNRECOGNIZED `schema` IS BLOCKED, never best-effort. A manifest this CLI
+ * does not understand is a manifest whose overwrite set it cannot bound.
+ */
+import { type ZonePathError, type ZoneSet } from "./zonePath.js";
+/** The only schema this CLI understands. */
+export declare const SUPPORTED_SCHEMA = 1;
+export type ManifestRefusal = {
+    kind: "unparseable";
+} | {
+    kind: "unsupported_schema";
+    schema: unknown;
+} | {
+    kind: "malformed";
+} | {
+    kind: "floor";
+    error: ZonePathError;
+};
+export type ManifestResult = {
+    ok: true;
+    zones: ZoneSet;
+} | {
+    ok: false;
+    refusal: ManifestRefusal;
+};
+/**
+ * Parse and floor-validate a manifest document.
+ *
+ * The floor runs over the WHOLE set before any caller may read a zone, and ONE
+ * failing entry refuses the WHOLE manifest. A per-entry skip looks like
+ * robustness and is the smuggling path — it is how one hostile entry rides in
+ * behind twenty good ones, with the twenty good writes making the report look
+ * normal.
+ */
+export declare function parseZoneManifest(raw: string): ManifestResult;
+export type Zone = "platform" | "creator" | "unlisted";
+/**
+ * Which zone a path is in.
+ *
+ * `unlisted` is a first-class answer and it means LEAVE ALONE — never read,
+ * never written. Every file the creator added is unlisted, which is the whole
+ * reason the lists are enumerated rather than inferred.
+ *
+ * This may only be called on a manifest the floor has already accepted, which is
+ * why it takes a validated `ZoneSet` rather than a raw document: the type is the
+ * reminder that permissibility was decided elsewhere and earlier.
+ */
+export declare function zoneOf(zones: ZoneSet, path: string): Zone;
+/** The overwrite set: exactly the `platform` list, in manifest order. */
+export declare function overwriteSet(zones: ZoneSet): string[];

package/dist/platform/zones.js

@@ -0,0 +1,79 @@
+/**
+ * `.vincentt-template.json` — the template's own per-version zone manifest.
+ *
+ * It is the authority for WHICH OF THE TWO ZONES a permissible path belongs to.
+ * It is never the authority for WHETHER a path is permissible: that is the
+ * floor, which is code, ships in the CLI, is identical for every template
+ * version, and runs BEFORE anything here consults a zone.
+ *
+ * Per-version because a project scaffolded from 1.2.0 needs 1.2.0's set, and
+ * only the 1.2.0 tag authoritatively knows it. Enumerated arrays with no globs,
+ * because the default must be LEAVE ALONE — an implicit rule claims every file
+ * the creator ever added, including one named `Scene2.tsx`, and the day a
+ * template file ships unclassified the default becomes destroy the creator's
+ * work.
+ *
+ * AN UNRECOGNIZED `schema` IS BLOCKED, never best-effort. A manifest this CLI
+ * does not understand is a manifest whose overwrite set it cannot bound.
+ */
+import { validateZoneSet } from "./zonePath.js";
+/** The only schema this CLI understands. */
+export const SUPPORTED_SCHEMA = 1;
+/**
+ * Parse and floor-validate a manifest document.
+ *
+ * The floor runs over the WHOLE set before any caller may read a zone, and ONE
+ * failing entry refuses the WHOLE manifest. A per-entry skip looks like
+ * robustness and is the smuggling path — it is how one hostile entry rides in
+ * behind twenty good ones, with the twenty good writes making the report look
+ * normal.
+ */
+export function parseZoneManifest(raw) {
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, refusal: { kind: "unparseable" } };
+    }
+    if (typeof doc !== "object" || doc === null) {
+        return { ok: false, refusal: { kind: "malformed" } };
+    }
+    const { schema, platform, creator } = doc;
+    if (schema !== SUPPORTED_SCHEMA) {
+        return { ok: false, refusal: { kind: "unsupported_schema", schema } };
+    }
+    if (!isStringArray(platform) || !isStringArray(creator)) {
+        return { ok: false, refusal: { kind: "malformed" } };
+    }
+    const zones = { platform, creator };
+    const error = validateZoneSet(zones);
+    if (error !== undefined)
+        return { ok: false, refusal: { kind: "floor", error } };
+    return { ok: true, zones };
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+/**
+ * Which zone a path is in.
+ *
+ * `unlisted` is a first-class answer and it means LEAVE ALONE — never read,
+ * never written. Every file the creator added is unlisted, which is the whole
+ * reason the lists are enumerated rather than inferred.
+ *
+ * This may only be called on a manifest the floor has already accepted, which is
+ * why it takes a validated `ZoneSet` rather than a raw document: the type is the
+ * reminder that permissibility was decided elsewhere and earlier.
+ */
+export function zoneOf(zones, path) {
+    if (zones.platform.includes(path))
+        return "platform";
+    if (zones.creator.includes(path))
+        return "creator";
+    return "unlisted";
+}
+/** The overwrite set: exactly the `platform` list, in manifest order. */
+export function overwriteSet(zones) {
+    return [...zones.platform];
+}

package/dist/preview/api.d.ts

@@ -1,4 +1,5 @@
 import type { ResolvedConfig } from "../shared/config.js";
+import type { CountLimitDetail } from "../shared/countLimit.js";
 import { BackendError } from "../lib/backend.js";
 /** The mint response. Its key set is the cross-repo pin (contract table 2.11). */
 export interface MintedPreview {
@@ -27,6 +28,24 @@ export declare class PreviewRateLimitedError extends BackendError {
 export declare class PreviewConflictError extends BackendError {
     constructor(message: string);
 }
+/**
+ * The org is at its concurrent-live-preview ceiling.
+ *
+ * IT IS A SECOND 409 ON THE MINT ROUTE and it is told from the first by its
+ * CODE, never by its status. The two mean opposite things to a creator: a
+ * conflict says a preview for this folder is already running and to go watch it;
+ * the ceiling says no preview started and the organization is full. Collapsing
+ * them would tell a creator at their ceiling to watch a preview that does not
+ * exist.
+ *
+ * It carries the whole detail because the refusal IS the notice: the figures and
+ * the org name are the only things that make it actionable, and the CLI cannot
+ * obtain either anywhere else.
+ */
+export declare class PreviewLimitError extends BackendError {
+    readonly detail: CountLimitDetail;
+    constructor(message: string, detail: CountLimitDetail);
+}
 /**
  * The session is gone — `preview_session_ended`, the CLI's terminal branch.
  *

package/dist/preview/api.js

@@ -23,6 +23,28 @@ export class PreviewConflictError extends BackendError {
         this.name = "PreviewConflictError";
     }
 }
+/**
+ * The org is at its concurrent-live-preview ceiling.
+ *
+ * IT IS A SECOND 409 ON THE MINT ROUTE and it is told from the first by its
+ * CODE, never by its status. The two mean opposite things to a creator: a
+ * conflict says a preview for this folder is already running and to go watch it;
+ * the ceiling says no preview started and the organization is full. Collapsing
+ * them would tell a creator at their ceiling to watch a preview that does not
+ * exist.
+ *
+ * It carries the whole detail because the refusal IS the notice: the figures and
+ * the org name are the only things that make it actionable, and the CLI cannot
+ * obtain either anywhere else.
+ */
+export class PreviewLimitError extends BackendError {
+    detail;
+    constructor(message, detail) {
+        super(message, 409);
+        this.detail = detail;
+        this.name = "PreviewLimitError";
+    }
+}
 /**
  * The session is gone — `preview_session_ended`, the CLI's terminal branch.
  *
@@ -104,6 +126,13 @@ export async function mintPreviewSession(cfg, projectId, key, fetchImpl = fetch)
             throw new ProjectUnreachableError(body.message ?? "This project is not available to you.");
         }
         if (res.status === 409) {
+            // TWO 409s NOW LAND HERE and the CODE is what separates them. Reading the
+            // status alone would render the ceiling refusal as "a preview is already
+            // running for this folder" — a sentence that is false, that names a
+            // preview the creator does not have, and that sends them to watch it.
+            if (body.code === "preview_limit") {
+                throw new PreviewLimitError(body.message ?? "this organization is at its preview limit", body.detail ?? {});
+            }
             throw new PreviewConflictError(body.message ?? "a preview is already running for this folder");
         }
         throw new BackendError(body.message ?? `could not start a preview (${res.status})`, res.status);