@vincentt-xr/cli 0.16.0 → 0.18.0

package/dist/lib/settings.js

@@ -0,0 +1,284 @@
+// `vincentt.json`: the committed file that tells the CLI how an app runs.
+//
+// Precedence is flag > file > template default, per field. The file's PRESENCE
+// is the switch: absent, every value is today's template default; present, it is
+// the whole truth and a missing field is refused by name. That refusal is what
+// stops an outside app whose detection failed from silently running `npm run
+// dev` on 5173.
+//
+// Pure: the file read is injected, nothing here touches the network or spawns.
+import { constants as fsConstants, promises as fs } from "node:fs";
+import path from "node:path";
+import { CONTROL_CHARS, escapeControl } from "./terminalText.js";
+export const SETTINGS_FILE = "vincentt.json";
+export const SETTINGS_SCHEMA_URL = "https://vincentt.studio/schema/vincentt.json";
+export const SETTINGS_MAX_BYTES = 4096;
+export const SETTINGS_FIELDS = [
+    "dev.command",
+    "dev.port",
+    "build.command",
+    "build.output",
+];
+export const TEMPLATE_DEFAULTS = {
+    devCommand: "npm run dev",
+    devPort: 5173,
+    buildOutput: "dist",
+};
+export class SettingsError extends Error {
+    problem;
+    constructor(problem) {
+        super(describeProblem(problem));
+        this.problem = problem;
+        this.name = "SettingsError";
+    }
+}
+/** One sentence naming what is wrong, for advisories that are not the full refusal. */
+export function describeProblem(p) {
+    switch (p.kind) {
+        case "missing":
+            return `vincentt.json has no ${p.field}`;
+        case "unknown_key":
+            return `unknown setting "${escapeControl(p.key)}"`;
+        case "invalid_json":
+            return p.line !== undefined
+                ? `not valid JSON (line ${p.line}, column ${p.column})`
+                : "not valid JSON";
+        case "bad_value":
+            return `${p.field} ${p.message}`;
+        case "not_object":
+            return "not a JSON object";
+        case "too_large":
+            return `larger than ${SETTINGS_MAX_BYTES / 1024} KB`;
+        case "not_file":
+            return "not a regular file";
+    }
+}
+const ALLOWED = {
+    dev: ["command", "port"],
+    build: ["command", "output"],
+};
+const COMMAND_MAX = 512;
+/**
+ * The schema rule for one field's value, as the message a prompt or a refusal
+ * prints. `undefined` means the value is acceptable. Shared by the file parser,
+ * the joining prompts and the flag values, so there is one rule.
+ */
+export function validateField(field, value) {
+    switch (field) {
+        case "dev.command":
+        case "build.command":
+            if (typeof value !== "string" || value.trim() === "")
+                return "must be a command";
+            if (value.length > COMMAND_MAX)
+                return `must be at most ${COMMAND_MAX} characters`;
+            // A carriage return or an escape sequence could redraw the disclosure
+            // line while the shell runs the real string.
+            if (CONTROL_CHARS.test(value))
+                return "must not contain control characters";
+            return undefined;
+        case "dev.port":
+            if (typeof value !== "number" ||
+                !Number.isInteger(value) ||
+                value < 1 ||
+                value > 65535) {
+                return "must be a whole number from 1 to 65535";
+            }
+            return undefined;
+        case "build.output":
+            return validateOutput(value);
+    }
+}
+function validateOutput(value) {
+    const inside = "must be a folder inside this project, written as a relative path";
+    if (typeof value !== "string" || value === "")
+        return inside;
+    if (value.startsWith("/") || value.includes("\\") || /^[A-Za-z]:/.test(value))
+        return inside;
+    if (value.split("/").some((seg) => seg === ".."))
+        return inside;
+    if (CONTROL_CHARS.test(value))
+        return "must not contain control characters";
+    return undefined;
+}
+/** Parse a typed or flagged value into the field's type, then validate it. */
+export function coerceField(field, raw) {
+    const value = field === "dev.port" && /^\d+$/.test(raw.trim()) ? Number(raw.trim()) : raw.trim();
+    const message = validateField(field, value);
+    return message === undefined ? { ok: true, value } : { ok: false, message };
+}
+/** Parse the file's text. Throws SettingsError; never returns a partial object. */
+export function parseSettings(text) {
+    if (Buffer.byteLength(text, "utf8") > SETTINGS_MAX_BYTES) {
+        throw new SettingsError({ kind: "too_large" });
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        throw new SettingsError({ kind: "invalid_json", ...jsonErrorPosition(err, text) });
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new SettingsError({ kind: "not_object" });
+    }
+    const obj = raw;
+    for (const key of Object.keys(obj)) {
+        if (key === "$schema")
+            continue;
+        // Own keys only: `constructor` or `__proto__` must never read through the prototype.
+        if (!Object.prototype.hasOwnProperty.call(ALLOWED, key)) {
+            throw new SettingsError({ kind: "unknown_key", key });
+        }
+        const allowed = ALLOWED[key];
+        const section = obj[key];
+        if (typeof section !== "object" || section === null || Array.isArray(section)) {
+            throw new SettingsError({
+                kind: "bad_value",
+                field: `${key}.${allowed[0]}`,
+                value: section,
+                message: `must sit inside a "${key}" object`,
+            });
+        }
+        for (const sub of Object.keys(section)) {
+            if (!allowed.includes(sub))
+                throw new SettingsError({ kind: "unknown_key", key: `${key}.${sub}` });
+        }
+    }
+    if (obj.$schema !== undefined && typeof obj.$schema !== "string") {
+        throw new SettingsError({
+            kind: "bad_value",
+            field: "$schema",
+            value: obj.$schema,
+            message: "must be a URL string",
+        });
+    }
+    const out = obj;
+    for (const field of SETTINGS_FIELDS) {
+        const value = fieldOf(out, field);
+        if (value === undefined)
+            continue;
+        const message = validateField(field, value);
+        if (message !== undefined) {
+            throw new SettingsError({ kind: "bad_value", field, value, message });
+        }
+    }
+    return out;
+}
+function jsonErrorPosition(err, text) {
+    const message = err instanceof Error ? err.message : "";
+    const lc = /line (\d+) column (\d+)/.exec(message);
+    if (lc)
+        return { line: Number(lc[1]), column: Number(lc[2]) };
+    const pos = /position (\d+)/.exec(message);
+    if (!pos)
+        return {};
+    const offset = Number(pos[1]);
+    const before = text.slice(0, offset);
+    const line = before.split("\n").length;
+    const column = offset - before.lastIndexOf("\n");
+    return { line, column };
+}
+export function fieldOf(file, field) {
+    switch (field) {
+        case "dev.command":
+            return file.dev?.command;
+        case "dev.port":
+            return file.dev?.port;
+        case "build.command":
+            return file.build?.command;
+        case "build.output":
+            return file.build?.output;
+    }
+}
+/**
+ * Read `vincentt.json` without trusting what it is. Opened non-blocking so a
+ * FIFO cannot park the open, then checked on the OPEN descriptor to be a
+ * regular file of at most 4 KB, and read no further than one byte past the cap.
+ * A symlink to /dev/zero is a character device and is refused before any read.
+ * Throws ENOENT (absent) or SettingsError (present but unusable).
+ */
+export async function readSettingsText(abs) {
+    const handle = await fs.open(abs, fsConstants.O_RDONLY | fsConstants.O_NONBLOCK);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new SettingsError({ kind: "not_file" });
+        if (stat.size > SETTINGS_MAX_BYTES)
+            throw new SettingsError({ kind: "too_large" });
+        const buf = Buffer.alloc(SETTINGS_MAX_BYTES + 1);
+        const { bytesRead } = await handle.read(buf, 0, buf.length, 0);
+        if (bytesRead > SETTINGS_MAX_BYTES)
+            throw new SettingsError({ kind: "too_large" });
+        return buf.subarray(0, bytesRead).toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}
+const defaultIo = { readFile: readSettingsText };
+/**
+ * The file at `root`, or undefined when there is none. A present file that
+ * cannot be used throws: an unreadable file is never treated as absent, or a
+ * typo would silently restore the template defaults.
+ */
+export async function readSettings(root, io = defaultIo) {
+    let text;
+    try {
+        text = await io.readFile(path.join(root, SETTINGS_FILE));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+    return parseSettings(text);
+}
+/**
+ * Resolve the fields a verb needs. `need` scopes the refusal: preview never
+ * refuses over a missing build.output, and publish never over a missing dev
+ * port. build.command is never refused anywhere, because nothing runs it.
+ */
+export function resolveSettings(flags, file, defaults = TEMPLATE_DEFAULTS, need = ["dev", "build"]) {
+    const pick = (field, flagName, flagValue, fallback, required) => {
+        if (flagValue !== undefined)
+            return { value: flagValue, source: "flag", flag: flagName };
+        if (!file)
+            return { value: fallback, source: "default" };
+        const fromFile = fieldOf(file, field);
+        if (fromFile !== undefined)
+            return { value: fromFile, source: "vincentt.json" };
+        if (required)
+            throw new SettingsError({ kind: "missing", field, flag: flagName });
+        return { value: fallback, source: "default" };
+    };
+    const dev = need.includes("dev");
+    const build = need.includes("build");
+    const buildCommand = file?.build?.command;
+    return {
+        devCommand: pick("dev.command", "--dev-command", flags.devCommand, defaults.devCommand, dev),
+        devPort: pick("dev.port", "--port", flags.devPort, defaults.devPort, dev),
+        buildOutput: pick("build.output", "--dist", flags.buildOutput, defaults.buildOutput, build),
+        ...(buildCommand !== undefined
+            ? { buildCommand: { value: buildCommand, source: "vincentt.json" } }
+            : {}),
+    };
+}
+/** The file as joining writes it: 2-space indentation and a trailing newline. */
+export function serializeSettings(values) {
+    const out = { $schema: SETTINGS_SCHEMA_URL };
+    if (values["dev.command"] !== undefined || values["dev.port"] !== undefined) {
+        out.dev = {};
+        if (values["dev.command"] !== undefined)
+            out.dev.command = String(values["dev.command"]);
+        if (values["dev.port"] !== undefined)
+            out.dev.port = Number(values["dev.port"]);
+    }
+    if (values["build.command"] !== undefined || values["build.output"] !== undefined) {
+        out.build = {};
+        if (values["build.command"] !== undefined)
+            out.build.command = String(values["build.command"]);
+        if (values["build.output"] !== undefined)
+            out.build.output = String(values["build.output"]);
+    }
+    return JSON.stringify(out, null, 2) + "\n";
+}

package/dist/lib/settingsCopy.d.ts

@@ -0,0 +1,6 @@
+import type { Resolved, SettingsError } from "./settings.js";
+export type SettingsVerb = "preview" | "publish";
+/** The three source words, and only three. */
+export declare function sourceWords(r: Resolved<unknown>): string;
+/** Flow P2 and its publish twin. Every variant ends with what did not happen. */
+export declare function settingsRefusal(err: SettingsError, verb: SettingsVerb): string[];

package/dist/lib/settingsCopy.js

@@ -0,0 +1,99 @@
+// The settings lines shared by `preview` and `publish`: the refusal (2B.9) and
+// the per-value source words (2B.0 rule 1). Pure string functions.
+import { escapeControl } from "./terminalText.js";
+/** The three source words, and only three. */
+export function sourceWords(r) {
+    if (r.source === "flag")
+        return `from ${r.flag ?? "a flag"}`;
+    if (r.source === "vincentt.json")
+        return "from vincentt.json";
+    return "default (no vincentt.json)";
+}
+const REMEDY = {
+    "dev.command": {
+        edit: `"dev": { "command": "<command>" }`,
+        run: `vincentt preview --dev-command "<command>"`,
+    },
+    "dev.port": {
+        edit: `"dev": { "port": <port> }`,
+        run: "vincentt preview --port <port>",
+    },
+    "build.output": {
+        edit: `"build": { "output": "<folder>" }`,
+        run: "vincentt publish --dist <folder>",
+    },
+    "build.command": { edit: `"build": { "command": "<command>" }`, run: "" },
+};
+/** Flow P2 and its publish twin. Every variant ends with what did not happen. */
+export function settingsRefusal(err, verb) {
+    const last = verb === "preview" ? "  Nothing was started." : "  Nothing was uploaded.";
+    const p = err.problem;
+    switch (p.kind) {
+        case "missing": {
+            const remedy = REMEDY[p.field];
+            return [
+                "",
+                `✗ vincentt.json has no ${p.field}.`,
+                "",
+                "  This folder has a vincentt.json, so Vincentt uses only what it says. It does not",
+                "  fall back to the template's defaults.",
+                "",
+                `  Add it to vincentt.json:   ${remedy.edit}`,
+                `  Or pass it for one run:    ${remedy.run}`,
+                "",
+                last,
+                "",
+            ];
+        }
+        case "unknown_key":
+            return [
+                "",
+                `✗ vincentt.json has a setting Vincentt does not know: "${escapeControl(p.key)}".`,
+                "",
+                "  It accepts dev.command, dev.port, build.command and build.output.",
+                "",
+                last,
+                "",
+            ];
+        case "invalid_json":
+            return [
+                "",
+                p.line !== undefined
+                    ? `✗ vincentt.json is not valid JSON (line ${p.line}, column ${p.column}).`
+                    : "✗ vincentt.json is not valid JSON.",
+                "",
+                "  Fix the file so Vincentt can read it.",
+                "",
+                last,
+                "",
+            ];
+        case "bad_value":
+            return [
+                "",
+                `✗ vincentt.json has a ${p.field} Vincentt can't use: ${escapeControl(String(JSON.stringify(p.value)))}.`,
+                "",
+                `  It ${p.message}.`,
+                "",
+                last,
+                "",
+            ];
+        case "not_object":
+            return ["", "✗ vincentt.json is not a JSON object.", "", last, ""];
+        case "too_large":
+            return [
+                "",
+                "✗ vincentt.json is larger than 4 KB, more than a settings file holds.",
+                "",
+                last,
+                "",
+            ];
+        case "not_file":
+            return [
+                "",
+                "✗ vincentt.json is not a regular file, so Vincentt does not read it.",
+                "",
+                last,
+                "",
+            ];
+    }
+}

package/dist/lib/settle.d.ts

@@ -0,0 +1,61 @@
+import { type DetectProbes } from "./detect.js";
+import { type SettingsField } from "./settings.js";
+import type { Ask } from "../publish/prompt.js";
+import type { ProjectBinding } from "../shared/config.js";
+export interface JoinFlags {
+    devCommand?: string;
+    devPort?: string;
+    buildCommand?: string;
+    buildOutput?: string;
+}
+export interface SettleIo {
+    print: (line: string) => void;
+    /** Present only on a TTY. `--json` passes none. */
+    ask?: Ask;
+    /** Machine mode: print nothing, prompt nothing. */
+    json?: boolean;
+    /** Injected for tests; defaults to the real, capped, read-only file probes. */
+    probes?: DetectProbes;
+    /** Injected for tests; defaults to an exclusive create, so a race never overwrites. */
+    writeFile?: (abs: string, text: string) => Promise<void>;
+}
+export type JsonSource = "detected" | "flag";
+export interface JoinJson {
+    settings: {
+        template: boolean;
+        written: boolean;
+        file: "vincentt.json";
+        fields: Partial<Record<SettingsField, {
+            value: string | number;
+            source: JsonSource;
+            evidence: string;
+        }>>;
+        missing: {
+            field: SettingsField;
+            reason: string;
+            remedy?: {
+                edit: string;
+                flag: string;
+            };
+        }[];
+        differs: {
+            field: SettingsField;
+            file: string | number;
+            folder: string | number;
+            evidence: string;
+        }[];
+    };
+    advisories: "git_lfs"[];
+}
+/** The real probes: read-only, capped, and confined to the project's own tree. */
+export declare function fsProbes(root: string): DetectProbes;
+/**
+ * Settle the settings file for a folder whose binding was just written.
+ * Returns the `--json` shape; in text mode it has already printed the report.
+ */
+export interface SettleResult {
+    json: JoinJson;
+    /** A join report was printed, so the caller closes with its next-step line. */
+    reported: boolean;
+}
+export declare function settleSettings(root: string, binding: Pick<ProjectBinding, "template"> | undefined, flags: JoinFlags, io: SettleIo): Promise<SettleResult>;