@mizen-labs/cli 0.0.0-stage → 0.1.0

package/dist/init/edit.js

@@ -0,0 +1,119 @@
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { createTwoFilesPatch } from "diff";
+import { readOptional } from "../doctor/files.js";
+import { isNode, parseSource } from "../doctor/syntax.js";
+import { CliError } from "../errors.js";
+/** Stops init before any change. The headline names what init can't do. */
+export function conflict(message, detail) {
+    throw new CliError("conflict", `Can't set up Mizen. ${message}`, 1, detail);
+}
+export function position(value, key) {
+    if (!isNode(value) || typeof value[key] !== "number") {
+        return conflict("The parser did not provide a safe edit range.");
+    }
+    return value[key];
+}
+const TAB_INDENT = /^\t/mu;
+// Wraps the element at start..end in <name>. An element that starts its
+// line is wrapped as a block, one indent deeper; one inline stays inline.
+export function wrapElement(source, start, end, name) {
+    const element = source.slice(start, end);
+    const lineStart = source.lastIndexOf("\n", start - 1) + 1;
+    const indent = source.slice(lineStart, start);
+    if (indent.trim()) {
+        return { end, start, text: `<${name}>${element}</${name}>` };
+    }
+    const unit = TAB_INDENT.test(source) ? "\t" : "  ";
+    const newline = source.includes("\r\n") ? "\r\n" : "\n";
+    const inner = element.split(newline).join(`${newline}${unit}`);
+    return {
+        end,
+        start,
+        text: `<${name}>${newline}${indent}${unit}${inner}${newline}${indent}</${name}>`,
+    };
+}
+export function changes(source, edits) {
+    let cursor = source.length;
+    let result = source;
+    for (const edit of edits.toSorted((a, b) => b.start - a.start || b.end - a.end)) {
+        if (edit.end > cursor) {
+            return conflict("Overlapping source edits require manual setup.");
+        }
+        result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
+        cursor = edit.start;
+    }
+    parseSource(result);
+    return result;
+}
+export function fileEdit(path, before, after) {
+    if (before === after) {
+        return null;
+    }
+    return {
+        after,
+        before,
+        diff: createTwoFilesPatch(path, path, before ?? "", after),
+        path,
+    };
+}
+export function addProperty(object, key, value) {
+    if (!Array.isArray(object.properties)) {
+        return conflict("Computed configuration needs manual setup.");
+    }
+    const last = object.properties.at(-1);
+    if (!last) {
+        return {
+            end: position(object, "start") + 1,
+            start: position(object, "start") + 1,
+            text: `${key}: ${value}`,
+        };
+    }
+    // Insert before the first member, leaving trailing comments and commas untouched.
+    const at = position(object.properties[0], "start");
+    return { end: at, start: at, text: `${key}: ${value}, ` };
+}
+export async function sourceFile(project, candidates, create) {
+    const results = await Promise.all(candidates.map(async (path) => ({
+        path,
+        source: await readOptional(join(project, path)),
+    })));
+    const found = results.filter((item) => item.source !== null);
+    if (found.length > 1) {
+        return conflict(`Multiple candidates exist: ${found.map((candidate) => candidate.path).join(", ")}. Select one before setup.`);
+    }
+    if (!(found.length || create)) {
+        return conflict(`No conventional root file found: ${candidates.join(", ")}.`);
+    }
+    if (!found.length) {
+        return { before: null, path: candidates[0], source: create };
+    }
+    const [file] = found;
+    const metadata = await lstat(join(project, file.path));
+    if (!metadata.isFile() || metadata.nlink !== 1) {
+        return conflict(`Use a regular, unlinked source file for ${file.path}.`);
+    }
+    validateSyntax(file.source, file.path);
+    return {
+        before: file.source,
+        path: file.path,
+        source: file.source,
+    };
+}
+export async function unchanged(path, expected) {
+    const source = await readOptional(path);
+    if (source !== expected) {
+        conflict(`File changed since planning: ${path}. Rerun init to review a fresh plan.`);
+    }
+}
+function validateSyntax(source, path) {
+    try {
+        parseSource(source);
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError)) {
+            throw error;
+        }
+        conflict(`${path} has invalid or unsupported syntax. Repair it before setup.`);
+    }
+}

package/dist/init/imports.js

@@ -0,0 +1,83 @@
+import { imports, isNode, literal, nameOf, nodes, } from "../doctor/syntax.js";
+import { conflict, position } from "./edit.js";
+export function uniqueName(ast, preferred) {
+    const used = new Set(nodes(ast).map((node) => nameOf(node)));
+    let name = preferred;
+    let suffix = 1;
+    while (used.has(name)) {
+        name = `${preferred}${suffix}`;
+        suffix += 1;
+    }
+    return name;
+}
+/** The export's own name when the module leaves it free, else a Mizen alias. */
+export function bindingName(ast, exported) {
+    const used = new Set(nodes(ast).map((node) => nameOf(node)));
+    if (!used.has(exported)) {
+        return exported;
+    }
+    const alias = `Mizen${exported[0]?.toUpperCase()}${exported.slice(1)}`;
+    return uniqueName(ast, alias);
+}
+/** An import specifier, aliased only when the local name differs. */
+export function specifier(exported, local) {
+    return exported === local ? exported : `${exported} as ${local}`;
+}
+export function importedName(ast, exported, source) {
+    const found = imports(ast)
+        .filter((node) => literal(node.source) === source)
+        .flatMap((node) => (Array.isArray(node.specifiers) ? node.specifiers : []))
+        .filter((node) => isNode(node) &&
+        node.importKind !== "type" &&
+        nameOf(node.imported) === exported);
+    if (found.length > 1) {
+        return conflict(`Multiple ${exported} imports require manual review.`);
+    }
+    return found.length ? nameOf(found[0].local) : null;
+}
+export function defaultImport(ast, source) {
+    const specifiers = imports(ast)
+        .filter((node) => literal(node.source) === source)
+        .flatMap((node) => (Array.isArray(node.specifiers) ? node.specifiers : []))
+        .filter((node) => isNode(node) && node.type === "ImportDefaultSpecifier");
+    return specifiers.length === 1
+        ? nameOf(specifiers[0].local)
+        : null;
+}
+function insertAt(at, text) {
+    return { end: at, start: at, text };
+}
+// Where a module with no imports takes its first one: after its directives,
+// else before its first statement.
+function firstImport(program, statement, newline) {
+    const directives = Array.isArray(program.directives)
+        ? program.directives
+        : [];
+    const directive = directives.at(-1);
+    if (isNode(directive) && typeof directive.end === "number") {
+        return insertAt(directive.end, `${newline}${newline}${statement}`);
+    }
+    const body = Array.isArray(program.body) ? program.body : [];
+    const [first] = body;
+    if (isNode(first) && typeof first.start === "number") {
+        return insertAt(first.start, `${statement}${newline}${newline}`);
+    }
+    return insertAt(0, `${statement}${newline}`);
+}
+// New imports go after the module's last import, or before its first
+// statement when it has none, so the file keeps its own spacing. A
+// stylesheet goes first instead, so the app's own CSS can override it.
+export function importEdit(ast, statement, source, place = "last") {
+    const { program } = ast;
+    if (!isNode(program)) {
+        return conflict("No editable module body was found.");
+    }
+    const newline = source.includes("\r\n") ? "\r\n" : "\n";
+    const found = (Array.isArray(program.body) ? program.body : []).filter((node) => isNode(node) && node.type === "ImportDeclaration");
+    if (!found.length) {
+        return firstImport(program, statement, newline);
+    }
+    return place === "first"
+        ? insertAt(position(found[0], "start"), `${statement}${newline}`)
+        : insertAt(position(found.at(-1), "end"), `${newline}${statement}`);
+}

package/dist/init/init.js

@@ -0,0 +1,193 @@
+import { createHash } from "node:crypto";
+import { readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import spawn from "cross-spawn";
+import { doctor } from "../doctor/doctor.js";
+import { formatReport } from "../doctor/report.js";
+import { CliError, commandLine } from "../errors.js";
+import { plural, row, status } from "../output.js";
+import { conflict, unchanged } from "./edit.js";
+import { JOURNAL, planInit } from "./plan.js";
+import { applyFiles, restoreFiles } from "./transaction.js";
+async function validate(plan) {
+    await unchanged(join(plan.project, "package.json"), plan.manifestBefore);
+    await validateInputs(plan);
+    await Promise.all(plan.edits.map((edit) => unchanged(join(plan.project, edit.path), edit.before)));
+    const archive = plan.install?.archive;
+    if (archive &&
+        createHash("sha256")
+            .update(await readFile(archive.path))
+            .digest("hex") !== archive.sha256) {
+        conflict("The package archive changed after planning. Rerun init.");
+    }
+}
+function installDependencies(plan) {
+    if (!plan.install) {
+        return true;
+    }
+    const result = spawn.sync(plan.install.command, plan.install.args, {
+        cwd: plan.project,
+        killSignal: "SIGKILL",
+        maxBuffer: 2_000_000,
+        timeout: 600_000,
+    });
+    return !result.error && result.status === 0;
+}
+export async function init(options, catalog) {
+    const plan = await planInit(options, catalog);
+    const empty = plan.edits.length === 0 && !plan.install;
+    if (empty) {
+        return verifyUnchanged(plan, catalog);
+    }
+    if (options.dryRun || !options.yes) {
+        return {
+            message: plannedMessage(plan),
+            plan,
+            status: empty ? "unchanged" : "planned",
+            verification: null,
+        };
+    }
+    return applyPlan(plan, catalog);
+}
+async function applyPlan(plan, catalog) {
+    await validate(plan);
+    const journal = join(plan.project, JOURNAL);
+    await writeFile(journal, `${JSON.stringify({ plan, schemaVersion: 1 }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    let keepJournal = false;
+    try {
+        if (!installDependencies(plan)) {
+            return {
+                message: "Couldn't install dependencies. No source files changed, but package.json, lockfiles, or node_modules may have.",
+                plan,
+                status: "install-failed",
+                verification: null,
+            };
+        }
+        const before = await doctor(plan.project, catalog.nodeRange);
+        if (before.summary.errors) {
+            return {
+                message: "Doctor found errors after installing dependencies. No source files changed.",
+                plan,
+                status: "verification-failed",
+                verification: before,
+            };
+        }
+        await validateInputs(plan);
+        await applyFiles(plan.project, plan.edits);
+        const verification = await doctor(plan.project, catalog.nodeRange);
+        if (verification.status !== "healthy") {
+            await restoreFiles(plan.project, plan.edits);
+            return {
+                message: "Couldn't verify setup. Source edits were rolled back; dependency changes stay for review.",
+                plan,
+                status: "verification-failed",
+                verification,
+            };
+        }
+        return {
+            message: "Set up Mizen. Doctor passed.",
+            plan,
+            status: "applied",
+            verification,
+        };
+    }
+    catch (error) {
+        keepJournal = true;
+        throw recoveryFailure(journal, error);
+    }
+    finally {
+        if (!keepJournal) {
+            await rm(journal);
+        }
+    }
+}
+function plannedMessage(plan) {
+    const parts = [
+        ...(plan.edits.length ? [plural(plan.edits.length, "file edit")] : []),
+        ...(plan.install ? ["1 install"] : []),
+    ];
+    return `Planned ${parts.join(" and ")}. Nothing changed yet.`;
+}
+const PATCH_HEADER = /^(?:Index: |={10,})/u;
+// The unified diff without its banner lines, added lines green and removed
+// lines red.
+function formatDiff(style, diff) {
+    return diff
+        .split("\n")
+        .filter((line) => !PATCH_HEADER.test(line))
+        .map((line) => {
+        if (line.startsWith("+") && !line.startsWith("+++")) {
+            return style.pass(line);
+        }
+        if (line.startsWith("-") && !line.startsWith("---")) {
+            return style.fail(line);
+        }
+        return line;
+    })
+        .join("\n")
+        .trimEnd();
+}
+const FRAMEWORKS = {
+    next: "Next.js App Router",
+    start: "TanStack Start",
+    vite: "React + Vite",
+};
+function outcome(style, result) {
+    if (result.status === "planned") {
+        return result.message;
+    }
+    const kind = ["applied", "unchanged"].includes(result.status)
+        ? "pass"
+        : "fail";
+    return status(style, kind, result.message);
+}
+export function formatInit(style, result) {
+    const { install } = result.plan;
+    return [
+        row("Project", result.plan.project),
+        row("Framework", FRAMEWORKS[result.plan.framework]),
+        "",
+        ...result.plan.edits.flatMap((edit) => [formatDiff(style, edit.diff), ""]),
+        ...(install
+            ? [
+                row("Install", [
+                    commandLine([install.command, ...install.args]),
+                    "May update package.json, lockfiles, and node_modules.",
+                ]),
+                "",
+            ]
+            : []),
+        outcome(style, result),
+        ...(result.verification && result.verification.status !== "healthy"
+            ? ["", formatReport(style, result.verification)]
+            : []),
+    ].join("\n");
+}
+async function verifyUnchanged(plan, catalog) {
+    const verification = await doctor(plan.project, catalog.nodeRange);
+    const healthy = verification.status === "healthy";
+    return {
+        message: healthy
+            ? "Mizen is already set up. Doctor passed."
+            : "Existing setup needs review. Resolve the doctor findings before init.",
+        plan,
+        status: healthy ? "unchanged" : "verification-failed",
+        verification,
+    };
+}
+function recoveryFailure(journal, cause) {
+    const failure = new CliError("recovery_required", "Couldn't finish setup. Source edits may be partly applied.", 1, {
+        rows: [
+            ["Journal", journal],
+            [
+                "Recovery",
+                "Restore or finish the recorded edits, then remove the journal.",
+            ],
+        ],
+    });
+    failure.cause = cause;
+    return failure;
+}
+async function validateInputs(plan) {
+    await Promise.all((plan.inputs ?? []).map((input) => unchanged(join(plan.project, input.path), input.before)));
+}

package/dist/init/plan.js

@@ -0,0 +1,88 @@
+import { lstat, realpath } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { readOptional } from "../doctor/files.js";
+import { versionCheck } from "../doctor/packages.js";
+import { frameworkOf, targetProject } from "../doctor/project.js";
+import { diagnosticDetail } from "../doctor/report.js";
+import { CliError } from "../errors.js";
+import { configEdit } from "./config.js";
+import { installation, managerFor } from "./dependencies.js";
+import { conflict } from "./edit.js";
+import { rootEdit } from "./styles.js";
+export const JOURNAL = ".mizen-init-journal.json";
+async function safePath(project, edit) {
+    const path = join(project, edit.path);
+    const resolved = edit.before === null ? path : await realpath(path);
+    const within = relative(project, resolved);
+    if (within.startsWith(`..${sep}`) || within === "..") {
+        conflict(`Source path leaves the selected app: ${edit.path}.`);
+    }
+    // biome-ignore lint/suspicious/noBitwiseOperators: POSIX owner-write permission bit.
+    if (edit.before !== null && !((await lstat(path)).mode & 0o200)) {
+        conflict(`Source file is read-only: ${edit.path}.`);
+    }
+}
+async function projectContext(options, catalog) {
+    const target = await targetProject(resolve(options.cwd ?? process.cwd()));
+    if (!(target.project && target.manifest)) {
+        throw new CliError("project_not_found", `Couldn't find an app to set up. ${target.diagnostic?.message ?? ""}`.trim(), 1, {
+            next: {
+                argv: ["mizen", "init", "--cwd", "<APP_DIR>"],
+                benefit: "Select the app",
+            },
+            ...(target.diagnostic ? diagnosticDetail(target.diagnostic) : {}),
+        });
+    }
+    const project = await realpath(target.project);
+    await validateProjectFiles(project);
+    const framework = frameworkOf(target.manifest);
+    if (framework === "unknown") {
+        return conflict("Init supports an unambiguous Next.js App Router, TanStack Start, or React + Vite app.");
+    }
+    if (versionCheck("node", process.versions.node, catalog.nodeRange, [])
+        .status !== "pass") {
+        return conflict(`Use Node ${catalog.nodeRange} before init.`);
+    }
+    return { framework, manifest: target.manifest, project };
+}
+async function validateProjectFiles(project) {
+    const manifestStat = await lstat(join(project, "package.json"));
+    if (!manifestStat.isFile() || manifestStat.nlink !== 1) {
+        return conflict("The app manifest must be a regular, unlinked file before init.");
+    }
+    if ((await readOptional(join(project, JOURNAL))) !== null) {
+        return conflict(`An interrupted init journal exists at ${join(project, JOURNAL)}. Review its recorded edits and restore or finish them before removing the journal.`);
+    }
+}
+export async function planInit(options, catalog) {
+    const { project, manifest, framework } = await projectContext(options, catalog);
+    const inputs = framework === "vite"
+        ? [
+            {
+                before: await readOptional(join(project, "index.html")),
+                path: "index.html",
+            },
+        ]
+        : [];
+    const manager = await managerFor(project, options.packageManager);
+    const [config, root] = await Promise.all([
+        configEdit(project, framework),
+        rootEdit(project, framework),
+    ]);
+    const edits = [config, root].filter((edit) => edit !== null);
+    await Promise.all(edits.map((edit) => safePath(project, edit)));
+    const install = await installation(project, manifest, catalog.uiVersion, options.package, options.feature ?? [], manager);
+    const manifestBefore = await readOptional(join(project, "package.json"));
+    if (!manifestBefore) {
+        return conflict("The app manifest changed while planning. Rerun init.");
+    }
+    return {
+        edits,
+        framework,
+        inputs,
+        install,
+        manifestBefore,
+        project,
+        uiVersion: catalog.uiVersion,
+    };
+}

package/dist/init/release.js

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { list } from "tar";
+import { parseManifest } from "../doctor/files.js";
+import { CliError } from "../errors.js";
+import { conflict } from "./edit.js";
+async function inspectArchive(specifier, expectedVersion) {
+    const path = resolve(specifier);
+    const info = await stat(path);
+    if (!info.isFile() || info.size > 50_000_000) {
+        return conflict("Use a local Mizen .tgz archive smaller than 50 MB.");
+    }
+    const sources = [];
+    let invalid = false;
+    await list({
+        file: path,
+        filter: (entry) => entry === "package/package.json",
+        onReadEntry(entry) {
+            if (entry.type !== "File" || entry.size > 1_000_000) {
+                invalid = true;
+                return;
+            }
+            const chunks = [];
+            entry.on("data", (data) => {
+                chunks.push(Buffer.from(data));
+            });
+            entry.on("end", () => {
+                sources.push(Buffer.concat(chunks).toString("utf8"));
+            });
+        },
+        strict: true,
+    });
+    if (invalid || sources.length !== 1) {
+        return conflict("The archive must contain one package/package.json.");
+    }
+    const manifest = parseManifest(sources[0], path);
+    if (manifest.name !== "@mizen-labs/ui" ||
+        manifest.version !== expectedVersion) {
+        return conflict(`Use an @mizen-labs/ui ${expectedVersion} archive matching this CLI's catalog.`);
+    }
+    return {
+        manifest,
+        path,
+        sha256: createHash("sha256")
+            .update(await readFile(path))
+            .digest("hex"),
+    };
+}
+export async function releaseArchive(specifier, version) {
+    try {
+        return await inspectArchive(specifier, version);
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            throw error;
+        }
+        return conflict(`Cannot read a valid Mizen archive at ${resolve(specifier)}. Check the file and retry.`);
+    }
+}

package/dist/init/styles.js

@@ -0,0 +1,96 @@
+import { imports, isNode, literal, nameOf, nodes, parseSource, property, } from "../doctor/syntax.js";
+import { viteRootEdit } from "../vite/init.js";
+import { member } from "./config.js";
+import { addProperty, changes, conflict, fileEdit, position, sourceFile, } from "./edit.js";
+import { defaultImport, importEdit, uniqueName } from "./imports.js";
+import { themeSource } from "./theme.js";
+function startRoute(ast) {
+    const bindings = imports(ast)
+        .filter((node) => literal(node.source) === "@tanstack/react-router")
+        .flatMap((node) => (Array.isArray(node.specifiers) ? node.specifiers : []))
+        .filter((node) => isNode(node) && nameOf(node.imported) === "createRootRoute")
+        .map((node) => (isNode(node) ? nameOf(node.local) : null));
+    const calls = nodes(ast).filter((node) => node.type === "CallExpression" && bindings.includes(nameOf(node.callee)));
+    if (calls.length !== 1 || !Array.isArray(calls[0].arguments)) {
+        return conflict("A single conventional createRootRoute call is required.");
+    }
+    const [config] = calls[0].arguments;
+    if (!isNode(config) || config.type !== "ObjectExpression") {
+        return conflict("Computed root route configuration requires manual setup.");
+    }
+    return config;
+}
+function headObject(head) {
+    if (!isNode(head) ||
+        head.type !== "ArrowFunctionExpression" ||
+        !isNode(head.body) ||
+        head.body.type !== "ObjectExpression") {
+        return conflict("Root head must be an arrow returning a literal object. Configure the stylesheet link manually.");
+    }
+    return head.body;
+}
+function linksChange(head, binding) {
+    const object = headObject(head);
+    const link = `{ href: ${binding}, rel: "stylesheet" }`;
+    if (!member(object, "links")) {
+        return addProperty(object, "links", `[${link}]`);
+    }
+    const links = property(object, "links");
+    if (!isNode(links) ||
+        links.type !== "ArrayExpression" ||
+        !Array.isArray(links.elements)) {
+        return conflict("Computed head links require manual setup.");
+    }
+    if (links.elements.some((node) => nameOf(property(node, "href")) === binding &&
+        literal(property(node, "rel")) === "stylesheet")) {
+        return null;
+    }
+    const at = position(links, "start") + 1;
+    return {
+        end: at,
+        start: at,
+        text: `${link}${links.elements.length ? ", " : ""}`,
+    };
+}
+function startStyles(source) {
+    const ast = parseSource(source);
+    const imported = defaultImport(ast, "@mizen-labs/ui/styles.css?url");
+    const binding = imported ?? uniqueName(ast, "mizenStylesheet");
+    const config = startRoute(ast);
+    const edits = [];
+    if (!imported) {
+        edits.push(importEdit(ast, `import ${binding} from "@mizen-labs/ui/styles.css?url";`, source));
+    }
+    if (member(config, "head")) {
+        const link = linksChange(property(config, "head"), binding);
+        if (link) {
+            edits.push(link);
+        }
+    }
+    else {
+        edits.push(addProperty(config, "head", `() => ({ links: [{ href: ${binding}, rel: "stylesheet" }] })`));
+    }
+    return changes(source, edits);
+}
+function nextStyles(source) {
+    const ast = parseSource(source);
+    const existing = imports(ast).filter((node) => literal(node.source) === "@mizen-labs/ui/styles.css");
+    if (existing.length) {
+        return source;
+    }
+    return changes(source, [
+        importEdit(ast, 'import "@mizen-labs/ui/styles.css";', source, "first"),
+    ]);
+}
+export async function rootEdit(project, framework) {
+    if (framework === "vite") {
+        return viteRootEdit(project);
+    }
+    const roots = framework === "next"
+        ? ["app/layout", "src/app/layout"]
+        : ["src/routes/__root", "app/routes/__root"];
+    const file = await sourceFile(project, roots.flatMap((path) => ["tsx", "jsx", "ts", "js"].map((extension) => `${path}.${extension}`)));
+    const themed = themeSource(file.source, framework);
+    const after = framework === "next" ? nextStyles(themed) : startStyles(themed);
+    return fileEdit(file.path, file.before, after);
+}