@velarscript/cli 0.12.1 → 0.14.0

package/dist/cli.js

@@ -7,12 +7,10 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import { cp, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
-import { createRequire } from "node:module";
-import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
-import { tmpdir } from "node:os";
+import { copyFile, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, parse as parsePath, relative, resolve } from "node:path";
+import { homedir, tmpdir } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { formatSource } from "@velarscript/compiler";
 import { createVelarProject, parseCreateArguments } from "create-velar";
 import { projectImportKey } from "./project.js";
 import { checkResolvedProject, discoverVelarSources, formatCheckOutput, projectTestModules } from "./project-check.js";
@@ -21,10 +19,11 @@ import { runDevServer } from "./dev-server.js";
 import { nodeApplicationConfig, nodeApplicationEntry, nodeApplicationLauncherSource, runNodeApplication, runNodeDevelopment, } from "./node-application.js";
 import { createFrameworkArtifacts } from "./framework-host.js";
 import { resolveVelarProject } from "./config.js";
-import { STANDARD_MODULE_ADAPTER_DEPENDENCIES, standardModuleClosure, standardModuleSource, standardModuleSources } from "./standard-modules.js";
+import { standardModuleClosure, standardModuleSource, standardModuleSources } from "./standard-modules.js";
 import { runTests } from "./test-runner.js";
 import { runProgram } from "./program-runner.js";
-import { buildProductionFramework, writeProductionManifest } from "./production-build.js";
+import { buildProductionFramework, PRODUCTION_MANIFEST_NAME, writeProductionManifest } from "./production-build.js";
+import { formatSourceChecked } from "./format-guard.js";
 import { VELAR_VERSION } from "./version.js";
 import { assertRequiredPublicAssets, copyPublicAssets, writeStaticDeployment } from "./static-deployment.js";
 import { verifyProductionBuild } from "./production-verifier.js";
@@ -37,8 +36,8 @@ import { loadApplicationPackageHost, validateApplicationPackageResult } from "./
 import { buildLanguageServerTool } from "./language-server-tool.js";
 import { applyProjectMechanicalFixes } from "./mechanical-fixer.js";
 import { bundleStandaloneJavaScript, needsStandaloneJavaScriptBundle } from "./standalone-build.js";
-import { resolveInstalledPackageRoot } from "./installed-package.js";
 import { BUILD_STAGING_MARKER } from "./build-staging.js";
+import { writeServerConfigurationDependency, writeWebSocketDependency } from "./node-runtime-dependencies.js";
 import { assertUniqueEmbeddedModuleOutputs, embeddedModuleFileContents, embeddedModuleOutputPath, VELAR_EMBEDDED_MODULE_MARKER, } from "./embedded-modules.js";
 import { resourceOutputRelativePath, writeBuildResourcePackageManifests, writeProjectResources } from "./resource-output.js";
 async function main(arguments_) {
@@ -97,10 +96,11 @@ async function main(arguments_) {
             core: "ai-skill.md",
             web: "ai-skill-web.md",
             node: "ai-skill-node.md",
+            server: "ai-skill-server.md",
             desktop: "ai-skill-desktop.md",
         });
         if (rest.length > 1 || files[kind] === undefined) {
-            process.stderr.write("velar skill: expected core, web, node, or desktop\n");
+            process.stderr.write("velar skill: expected core, web, node, server, or desktop\n");
             return 2;
         }
         process.stdout.write(await readFile(new URL(`../skill/${files[kind]}`, import.meta.url), "utf8"));
@@ -338,10 +338,19 @@ async function main(arguments_) {
             return 1;
         }
         const changed = [];
+        const unstable = [];
         try {
             for (const input of inputs) {
                 const source = await readVelarSourceFile(input);
-                const formatted = formatSource(source, { extensions: formattingExtensions });
+                const { text: formatted, stable } = formatSourceChecked(source, { extensions: formattingExtensions });
+                // Formatting is idempotent by contract. A result the formatter would
+                // change again is a formatter defect, and writing it would replace a
+                // module that compiles with one that may not, so the file keeps the
+                // bytes the author wrote and the command reports the defect.
+                if (!stable) {
+                    unstable.push(input);
+                    continue;
+                }
                 if (formatted === source)
                     continue;
                 changed.push(input);
@@ -353,6 +362,12 @@ async function main(arguments_) {
             process.stderr.write(`velar format: ${hostErrorMessage(error)}\n`);
             return 1;
         }
+        if (unstable.length > 0) {
+            for (const input of unstable) {
+                process.stderr.write(`velar format: ${displayPath(input)}: the formatter did not reach a fixed point; the file was left unchanged\n`);
+            }
+            return 1;
+        }
         if (parsed.check && changed.length > 0) {
             for (const input of changed)
                 process.stderr.write(`${displayPath(input)} is not formatted\n`);
@@ -381,8 +396,11 @@ async function main(arguments_) {
             projectConfig = await resolveVelarProject(parsed.input);
             if (projectConfig.framework)
                 await runDevServer(projectConfig, parsed.port ?? 5173);
-            else if (nodeApplicationConfig(projectConfig))
-                await runNodeDevelopment(projectConfig, parsed.port === null ? {} : { port: parsed.port });
+            else if (nodeApplicationConfig(projectConfig)) {
+                if (parsed.port !== null)
+                    throw new Error("Node application host and port belong to velar/server configuration; --port is available only to Web and Desktop development servers");
+                await runNodeDevelopment(projectConfig);
+            }
             else
                 throw new Error("the project does not declare a Web, Desktop, or Node application target");
         }
@@ -400,11 +418,7 @@ async function main(arguments_) {
         }
         try {
             const projectConfig = await resolveVelarProject(parsed.input);
-            const overrides = {
-                ...(parsed.host === null ? {} : { host: parsed.host }),
-                ...(parsed.port === null ? {} : { port: parsed.port }),
-            };
-            return await runNodeApplication(projectConfig, overrides);
+            return await runNodeApplication(projectConfig);
         }
         catch (error) {
             process.stderr.write(`velar serve: ${hostErrorMessage(error)}\n`);
@@ -442,7 +456,7 @@ async function main(arguments_) {
         }
         return runTests(projectConfig, parsed.input);
     }
-    const parsed = command === "package" ? parsePackageArguments(rest) : parseCommandArguments(rest);
+    const parsed = command === "package" ? parsePackageArguments(rest) : parseCommandArguments(rest, command === "build");
     if (typeof parsed === "string") {
         process.stderr.write(`velar ${command}: ${parsed}\n`);
         return 2;
@@ -470,7 +484,13 @@ async function main(arguments_) {
     }
     if (command === "check") {
         const count = checked.compiled.size;
-        process.stdout.write(`Checked ${count} module${count === 1 ? "" : "s"} from ${displayInput(parsed.input, projectConfig)}\n`);
+        // D89: a passing check that carried advisories says how many. Folding them
+        // into a silent "checked N modules" would hide the one thing the advisory
+        // channel exists to make impossible to miss; the exit code stays 0 either
+        // way, because an advisory is not a failure.
+        const advisories = checked.advisories.length;
+        process.stdout.write(`Checked ${count} module${count === 1 ? "" : "s"} from ${displayInput(parsed.input, projectConfig)}`
+            + `${advisories > 0 ? ` — ${advisories} advisor${advisories === 1 ? "y" : "ies"}` : ""}\n`);
         return 0;
     }
     if (command === "package") {
@@ -490,7 +510,7 @@ async function main(arguments_) {
                     if (buildRequests > 1)
                         throw new Error("application package host requested more than one framework build");
                     const outputDirectory = packageFrameworkOutput(projectConfig.root, requestedOutput);
-                    frameworkBuild = writeFrameworkProductionApplication(project, outputDirectory);
+                    frameworkBuild = writeFrameworkProductionApplication(project, outputDirectory, { forced: false, declared: false });
                     await frameworkBuild;
                 },
             });
@@ -535,9 +555,15 @@ async function main(arguments_) {
         return 0;
     }
     const outputDirectory = parsed.outputDirectory ? resolve(parsed.outputDirectory) : projectConfig.outDir;
+    // `outDir` is the project manifest's own declaration of a directory velar
+    // owns, and config.ts already refuses one that is the project root or that
+    // overlaps the entry or the public directory. `--out-dir` carries no such
+    // declaration, so a path it names has to prove ownership before the build
+    // replaces what is there.
+    const replacement = { forced: parsed.force, declared: outputDirectory === projectConfig.outDir };
     if (project.framework) {
         try {
-            await writeFrameworkProductionApplication(project, outputDirectory);
+            await writeFrameworkProductionApplication(project, outputDirectory, replacement);
         }
         catch (error) {
             process.stderr.write(`velar build: ${hostErrorMessage(error)}\n`);
@@ -549,7 +575,7 @@ async function main(arguments_) {
     const nodeConfig = nodeApplicationConfig(projectConfig);
     if (nodeConfig) {
         try {
-            await writeNodeProductionApplication(project, outputDirectory, nodeConfig);
+            await writeNodeProductionApplication(project, outputDirectory, nodeConfig, replacement);
         }
         catch (error) {
             process.stderr.write(`velar build: ${hostErrorMessage(error)}\n`);
@@ -558,7 +584,14 @@ async function main(arguments_) {
         process.stdout.write(`Built production Node app -> ${outputDirectory}\n`);
         return 0;
     }
-    const staging = await prepareBuildStaging(outputDirectory);
+    let staging;
+    try {
+        staging = await prepareBuildStaging(outputDirectory, replacement);
+    }
+    catch (error) {
+        process.stderr.write(`velar build: ${hostErrorMessage(error)}\n`);
+        return 1;
+    }
     try {
         assertUniqueEmbeddedModuleOutputs(project.modules.map((module) => ({
             ownerPath: join(staging, module.relativePath.replace(/\.vel$/, ".js")),
@@ -582,12 +615,12 @@ async function main(arguments_) {
     process.stdout.write(`Built ${project.modules.length} module${project.modules.length === 1 ? "" : "s"} -> ${outputDirectory}\n`);
     return 0;
 }
-async function writeFrameworkProductionApplication(project, outputDirectory) {
+async function writeFrameworkProductionApplication(project, outputDirectory, replacement) {
     if (!project.framework)
         throw new Error("the checked project has no framework host");
     const framework = project.framework;
     await assertRequiredPublicAssets(project.publicRoot, project.projectRoot, framework.host.requiredPublicAssets?.(framework.config) ?? []);
-    const staging = await prepareBuildStaging(outputDirectory);
+    const staging = await prepareBuildStaging(outputDirectory, replacement);
     try {
         await copyPublicAssets(project.publicRoot, staging);
         const production = await buildProductionFramework(project, staging);
@@ -608,9 +641,12 @@ async function writeFrameworkProductionApplication(project, outputDirectory) {
         throw error;
     }
 }
-async function writeNodeProductionApplication(project, outputDirectory, config) {
-    const entry = nodeApplicationEntry(project, config);
-    const staging = await prepareBuildStaging(outputDirectory);
+/** The receipt a node build leaves in its output; it also proves velar owns the directory. */
+const NODE_BUILD_MANIFEST_NAME = "velar-node.json";
+async function writeNodeProductionApplication(project, outputDirectory, config, replacement) {
+    const application = nodeApplicationEntry(project, config);
+    const entry = application.entry;
+    const staging = await prepareBuildStaging(outputDirectory, replacement);
     try {
         assertUniqueEmbeddedModuleOutputs(project.modules.map((module) => ({
             ownerPath: join(staging, module.relativePath.replace(/\.vel$/u, ".js")),
@@ -625,18 +661,18 @@ async function writeNodeProductionApplication(project, outputDirectory, config)
         await writeBuildResourcePackageManifests(project, staging);
         await writeNodeStandardModules(staging, project);
         await copyPublicAssets(project.publicRoot, join(staging, "public"), true);
+        if (requiredNodeStandardModules(project).has("velar/server")) {
+            await copyConventionalServerConfiguration(project.projectRoot, staging);
+        }
         const entryPath = `./${relative(project.sourceRoot, entry.inputPath).replace(/\.vel$/u, ".js").replaceAll("\\", "/")}`;
         const launcher = ".velar-node-entry.mjs";
-        await writeFile(join(staging, launcher), nodeApplicationLauncherSource(entryPath, config, {}, false), "utf8");
+        await writeFile(join(staging, launcher), nodeApplicationLauncherSource(entryPath, config, false, application.kind), "utf8");
         await writeFile(join(staging, "package.json"), `${JSON.stringify({ name: "velar-node-build", private: true, type: "module" }, null, 2)}\n`, "utf8");
-        await writeFile(join(staging, "velar-node.json"), `${JSON.stringify({
-            formatVersion: 1,
+        await writeFile(join(staging, NODE_BUILD_MANIFEST_NAME), `${JSON.stringify({
+            formatVersion: 2,
             kind: "velar-node-build",
             entry: launcher,
             app: config.app,
-            host: config.host,
-            port: config.port,
-            maxBodyBytes: config.maxBodyBytes,
             sourceMaps: config.build.sourceMaps,
         }, null, 2)}\n`, "utf8");
         await replaceOutputDirectory(staging, outputDirectory);
@@ -646,6 +682,37 @@ async function writeNodeProductionApplication(project, outputDirectory, config)
         throw error;
     }
 }
+const CONVENTIONAL_SERVER_CONFIGURATION_FILE = "application.yml";
+const UNSUPPORTED_CONVENTIONAL_SERVER_CONFIGURATION_FILES = ["application.yaml", "application.json"];
+async function copyConventionalServerConfiguration(projectRoot, outputRoot) {
+    for (const name of UNSUPPORTED_CONVENTIONAL_SERVER_CONFIGURATION_FILES) {
+        const path = join(projectRoot, name);
+        try {
+            const metadata = await lstat(path);
+            if (metadata.isSymbolicLink() || !metadata.isFile())
+                throw new Error(`Conventional Server configuration '${path}' must be a regular file`);
+            throw new Error(`Unsupported conventional Server configuration '${path}'; rename it to application.yml or use a non-conventional explicit configuration path`);
+        }
+        catch (error) {
+            if (!isHostErrorCode(error, "ENOENT"))
+                throw error;
+        }
+    }
+    const path = join(projectRoot, CONVENTIONAL_SERVER_CONFIGURATION_FILE);
+    try {
+        const metadata = await lstat(path);
+        if (metadata.isSymbolicLink() || !metadata.isFile())
+            throw new Error(`Conventional Server configuration '${path}' must be a regular file`);
+        if (metadata.size > 1024 * 1024)
+            throw new Error(`Conventional Server configuration '${path}' cannot exceed 1 MiB`);
+    }
+    catch (error) {
+        if (isHostErrorCode(error, "ENOENT"))
+            return;
+        throw error;
+    }
+    await copyFile(path, join(outputRoot, CONVENTIONAL_SERVER_CONFIGURATION_FILE));
+}
 function packageFrameworkOutput(root, input) {
     if (!isAbsolute(input))
         throw new Error("application package host requested a non-absolute framework output path");
@@ -661,8 +728,9 @@ function packageFrameworkOutput(root, input) {
  * output. A process cut can happen before or after either rename, so recovery
  * also finishes restoring the previous output when installation never began.
  */
-async function prepareBuildStaging(outputDirectory) {
+async function prepareBuildStaging(outputDirectory, replacement) {
     const normalizedOutput = resolve(outputDirectory);
+    await assertReplaceableBuildOutput(normalizedOutput, replacement);
     const parent = dirname(normalizedOutput);
     await mkdir(parent, { recursive: true });
     await recoverInterruptedBuilds(normalizedOutput);
@@ -677,6 +745,67 @@ async function prepareBuildStaging(outputDirectory) {
     await writeFile(join(staging, BUILD_STAGING_MARKER), `${JSON.stringify(ownership, null, 2)}\n`, "utf8");
     return staging;
 }
+/**
+ * A build replaces its output directory wholesale, so the path is accepted only
+ * when velar owns it: absent, empty, carrying a manifest a previous build wrote,
+ * or named by the project manifest's own `outDir`. Every other destructive path
+ * in this repository makes the same test first — `assertReplaceableReleaseOutput`
+ * in scripts/release-toolchain.mjs, `prepareDirectory` in reproduction.ts, and
+ * `createVelarProject` — and `--out-dir` was the one an author runs daily that
+ * did not. `--force` waives the ownership test and nothing else: the home
+ * directory, the filesystem root and a symbolic link stay refused.
+ */
+async function assertReplaceableBuildOutput(outputDirectory, replacement) {
+    const directory = resolve(outputDirectory);
+    if (directory === parsePath(directory).root || directory === resolve(homedir())) {
+        throw new Error(`refusing to replace '${directory}': a build output cannot be the filesystem root or the home directory`);
+    }
+    let metadata;
+    try {
+        metadata = await lstat(directory);
+    }
+    catch (error) {
+        if (isHostErrorCode(error, "ENOENT") || isHostErrorCode(error, "ENOTDIR"))
+            return;
+        throw error;
+    }
+    if (metadata.isSymbolicLink())
+        throw new Error(`refusing to replace '${directory}': it is a symbolic link`);
+    if (!metadata.isDirectory())
+        throw new Error(`refusing to replace '${directory}': it is not a directory`);
+    if (replacement.forced || replacement.declared)
+        return;
+    if ((await readdir(directory)).length === 0)
+        return;
+    if (await isBuildOutputDirectory(directory))
+        return;
+    throw new Error(`refusing to replace '${directory}': it is not empty and was not produced by velar build (pass --force to overwrite)`);
+}
+/**
+ * The three build shapes leave three different receipts: a framework build
+ * writes `velar-build.json`, a node build writes `velar-node.json`, and a build
+ * cut between the two renames leaves the staging marker naming this same output.
+ */
+async function isBuildOutputDirectory(directory) {
+    if (await buildStagingOwnership(directory, directory, null))
+        return true;
+    return await buildManifestKind(join(directory, PRODUCTION_MANIFEST_NAME)) === "velar-framework-build"
+        || await buildManifestKind(join(directory, NODE_BUILD_MANIFEST_NAME)) === "velar-node-build";
+}
+async function buildManifestKind(path) {
+    try {
+        const metadata = await lstat(path);
+        if (!metadata.isFile() || metadata.isSymbolicLink())
+            return null;
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        return Number.isSafeInteger(parsed.formatVersion) && typeof parsed.kind === "string" ? parsed.kind : null;
+    }
+    catch (error) {
+        if (isHostErrorCode(error, "ENOENT") || isHostErrorCode(error, "ENOTDIR") || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
 async function recoverInterruptedBuilds(outputDirectory) {
     const parent = dirname(outputDirectory);
     const prefix = `.velar-${basename(outputDirectory)}-`;
@@ -789,7 +918,8 @@ async function writeNodeStandardModules(outputRoot, project, replaceExisting = f
         await writeNodeStandardModulePackage(packageRoot, used, project);
         if (used.has("velar/websocket"))
             await writeWebSocketDependency(dirname(packageRoot));
-        await writeAdapterDependencies(dirname(packageRoot), used);
+        if (used.has("velar/server"))
+            await writeServerConfigurationDependency(dirname(packageRoot));
         return;
     }
     const ownership = await generatedRuntimePackageOwnership(packageRoot);
@@ -810,50 +940,14 @@ async function writeNodeStandardModules(outputRoot, project, replaceExisting = f
             await rename(staging, packageRoot);
         if (used.has("velar/websocket"))
             await writeWebSocketDependency(dirname(packageRoot));
-        await writeAdapterDependencies(dirname(packageRoot), used);
+        if (used.has("velar/server"))
+            await writeServerConfigurationDependency(dirname(packageRoot));
     }
     catch (error) {
         await rm(staging, { recursive: true, force: true });
         throw error;
     }
 }
-async function writeWebSocketDependency(nodeModulesRoot) {
-    const target = join(nodeModulesRoot, "ws");
-    try {
-        const manifest = JSON.parse(await readFile(join(target, "package.json"), "utf8"));
-        if (manifest.name !== "ws" || manifest.version !== "8.21.1")
-            throw new Error(`Refusing to use incompatible WebSocket runtime package '${target}'`);
-        return;
-    }
-    catch (error) {
-        if (!isHostErrorCode(error, "ENOENT"))
-            throw error;
-    }
-    const require = createRequire(import.meta.url);
-    const source = dirname(require.resolve("ws/package.json"));
-    await cp(source, target, { recursive: true, errorOnExist: true });
-}
-async function writeAdapterDependencies(nodeModulesRoot, used) {
-    const require = createRequire(import.meta.url);
-    for (const [moduleName, dependency] of STANDARD_MODULE_ADAPTER_DEPENDENCIES) {
-        if (!used.has(moduleName))
-            continue;
-        const target = join(nodeModulesRoot, dependency.packageName);
-        try {
-            const manifest = JSON.parse(await readFile(join(target, "package.json"), "utf8"));
-            if (manifest.name !== dependency.packageName || manifest.version !== dependency.version) {
-                throw new Error(`Refusing to use incompatible ${moduleName} runtime package '${target}'`);
-            }
-            continue;
-        }
-        catch (error) {
-            if (!isHostErrorCode(error, "ENOENT"))
-                throw error;
-        }
-        const source = await resolveInstalledPackageRoot(dependency.packageName, dependency.packageName, require);
-        await cp(source, target, { recursive: true, errorOnExist: true });
-    }
-}
 function requiredNodeStandardModules(project) {
     const sources = standardModuleSources(project.compilerExtensions);
     const roots = new Set(project.modules.flatMap((module) => module.result.dependencies
@@ -1018,13 +1112,17 @@ function parseFormatArguments(arguments_) {
     }
     return { input, check };
 }
-function parseCommandArguments(arguments_) {
+function parseCommandArguments(arguments_, allowForce = false) {
     let input = null;
     let output = null;
     let outputDirectory = null;
+    let force = false;
     for (let index = 0; index < arguments_.length; index += 1) {
         const argument = arguments_[index];
-        if (argument === "--out" || argument === "--out-dir") {
+        if (allowForce && argument === "--force") {
+            force = true;
+        }
+        else if (argument === "--out" || argument === "--out-dir") {
             const value = arguments_[index + 1];
             if (!value || value.startsWith("--")) {
                 return `${argument} requires a path`;
@@ -1049,7 +1147,7 @@ function parseCommandArguments(arguments_) {
             input = argument;
         }
     }
-    return { input, output, outputDirectory };
+    return { input, output, outputDirectory, force };
 }
 function parseReproArguments(arguments_) {
     let input = null;
@@ -1089,7 +1187,7 @@ function parsePackageArguments(arguments_) {
         return `unexpected extra input '${arguments_[1]}'`;
     if (arguments_[0]?.startsWith("-"))
         return `unknown option '${arguments_[0]}'`;
-    return { input: arguments_[0] ?? null, output: null, outputDirectory: null };
+    return { input: arguments_[0] ?? null, output: null, outputDirectory: null, force: false };
 }
 function parseDevArguments(arguments_) {
     let input = null;
@@ -1118,26 +1216,8 @@ function parseDevArguments(arguments_) {
 }
 function parseServeArguments(arguments_) {
     let input = null;
-    let host = null;
-    let port = null;
-    for (let index = 0; index < arguments_.length; index += 1) {
-        const argument = arguments_[index];
-        if (argument === "--host") {
-            const value = arguments_[index + 1];
-            if (!value || value.startsWith("--") || value.length > 255 || value.includes("\0"))
-                return "--host requires a bounded hostname or IP address";
-            host = value;
-            index += 1;
-        }
-        else if (argument === "--port") {
-            const value = arguments_[index + 1];
-            const parsed = value ? Number(value) : Number.NaN;
-            if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65_535)
-                return "--port requires an integer from 1 to 65535";
-            port = parsed;
-            index += 1;
-        }
-        else if (argument.startsWith("--")) {
+    for (const argument of arguments_) {
+        if (argument.startsWith("--")) {
             return `unknown option '${argument}'`;
         }
         else if (input) {
@@ -1147,7 +1227,7 @@ function parseServeArguments(arguments_) {
             input = argument;
         }
     }
-    return { input, host, port };
+    return { input };
 }
 function parseTestArguments(arguments_) {
     let input = null;
@@ -1303,8 +1383,8 @@ function printHelp(output = process.stdout) {
         "  velar remove <package>...",
         "  velar update [package...]",
         "  velar dev [entry.vel | project-directory] [--port <port>]",
-        "  velar serve [project-directory] [--host <host>] [--port <port>]",
-        "  velar build [entry.vel | project-directory] [--out-dir <directory>]",
+        "  velar serve [project-directory]",
+        "  velar build [entry.vel | project-directory] [--out-dir <directory>] [--force]",
         "  velar run [entry.vel | project-directory] [--stack] [-- <program-arguments>...]",
         "  velar verify [project-directory | build-directory]",
         "  velar preview [project-directory | build-directory] [--port <port>]",
@@ -1316,7 +1396,7 @@ function printHelp(output = process.stdout) {
         "  velar format [file.vel | project-directory] [--check]",
         "  velar fix [entry.vel | project-directory]",
         "  velar repro [entry.vel | project-directory] [--out-dir <directory>]",
-        "  velar skill [core|web|node|desktop]",
+        "  velar skill [core|web|node|server|desktop]",
         "  velar lsp",
         "  velar --version",
         "",
@@ -1334,9 +1414,9 @@ function printCommandHelp(command, output = process.stdout) {
         add: ["Usage: velar add <package[@version]>... [--dev]", "Adds npm registry packages and activates packages that declare velar.extension metadata."],
         remove: ["Usage: velar remove <package>...", "Removes npm packages and their extension-owned VelarScript project configuration."],
         update: ["Usage: velar update [package...]", "Updates all or selected direct dependencies within package.json ranges through npm."],
-        dev: ["Usage: velar dev [entry.vel | project-directory] [--port <1-65535>]", "Watches a framework app or last-good Node ServeApp; Web defaults to 5173 and Node reads node.port."],
-        serve: ["Usage: velar serve [project-directory] [--host <host>] [--port <1-65535>]", "Checks and runs a Node ServeApp with production runtime behavior; node.host and node.port provide the defaults."],
-        build: ["Usage: velar build [entry.vel | project-directory] [--out-dir <directory>]", "       velar build <single.vel> --out <file.js>", "Builds isolated Web/Desktop output, a standalone Node application, or JavaScript modules."],
+        dev: ["Usage: velar dev [entry.vel | project-directory] [--port <1-65535>]", "Watches a framework app or last-good Node server factory; --port applies only to Web and Desktop development servers."],
+        serve: ["Usage: velar serve [project-directory]", "Checks and runs a Node server factory with production runtime behavior; host and port belong to velar/server configuration."],
+        build: ["Usage: velar build [entry.vel | project-directory] [--out-dir <directory>] [--force]", "       velar build <single.vel> --out <file.js>", "Builds isolated Web/Desktop output, a standalone Node application, or JavaScript modules.", "--out-dir refuses a directory that is not empty and was not produced by a previous build; --force replaces one anyway."],
         package: ["Usage: velar package [project-directory]", "Packages an application through its target-owned native packaging host."],
         run: ["Usage: velar run [entry.vel | project-directory] [--stack] [-- <program-arguments>...]", "Compiles the resolved Core project and executes its entry module once on Node.js; arguments after '--' reach the program.", "--stack prints the full Node.js trace behind an uncaught program error instead of the VelarScript frames."],
         verify: ["Usage: velar verify [project-directory | build-directory]", "Verifies the exact production manifest, inventory, sizes, hashes, and relationships."],
@@ -1356,7 +1436,7 @@ function printCommandHelp(command, output = process.stdout) {
             "The bundle is extracted to a temporary directory and re-checked first; if the copy stops reproducing, the command says so rather than reporting a clean reproduction.",
             "The default location is .velar/repro inside the project, replaced on each run; a directory named with --out-dir must be empty.",
         ],
-        skill: ["Usage: velar skill [core|web|node|desktop]", "Prints one packaged, owner-specific VelarScript AI skill brief verbatim to stdout; the default is core."],
+        skill: ["Usage: velar skill [core|web|node|server|desktop]", "Prints one packaged, owner-specific VelarScript AI skill brief verbatim to stdout; the default is core."],
         lsp: ["Usage: velar lsp", "Runs the stdio language server for an editor host."],
     };
     output.write(["VelarScript Compiler", "", ...(details[command] ?? []), ""].join("\n"));