vovk-cli 0.2.0 → 0.3.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to `vovk-cli` are documented here. This file is the canonical record: noteworthy changes only, one short line each, linked to the pull request or commit that made them. GitHub Releases are not used.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.3.0-beta.0 - unreleased
+
+A cleanup release. `vovk-cli` is pre-1.0, so this minor carries breaking changes: `^0.2.0` does not match `0.3.0`.
+
+### Removed
+
+- The `vovk-client` package: the composed client generates into your source tree (`src/client`, or `client/` without a `src` folder) and is imported as `@/client`, so it survives `npm ci` and works under pnpm and Yarn PnP ([#29](https://github.com/finom/vovk/pull/29))
+- The `js` template family (`js`, `jsBase`, `schemaJs`, `openapiJs`): use `ts` ([#29](https://github.com/finom/vovk/pull/29))
+- The `prettier` dependency: prettifying resolves prettier from your project and warns once when it is missing ([#29](https://github.com/finom/vovk/pull/29))
+- Unused runtime deps `clone-deep`, `inflection` and `tar-stream` ([25a2f20](https://github.com/finom/vovk/commit/25a2f203)), the pinned linux rolldown binding ([d0cae19](https://github.com/finom/vovk/commit/d0cae19c)), and the pre-kebab collision guard in `vovk new` ([b7dc4b2](https://github.com/finom/vovk/commit/b7dc4b2a))
+
+### Changed
+
+- Composed client defaults: `fromTemplates: ['ts']`, `outDir: src/client`, `prettifyClient: true`; `vovk init` gitignores the client dir and no longer installs `vovk-client` ([#29](https://github.com/finom/vovk/pull/29))
+- Broken input fails fast, and the CLI reports what it actually did ([0ad9872](https://github.com/finom/vovk/commit/0ad9872e))
+
+### Fixed
+
+- The pruner only deletes files carrying the generated banner, so user files named like generated ones survive ([e9f269c](https://github.com/finom/vovk/commit/e9f269ce), [88065d0](https://github.com/finom/vovk/commit/88065d0c))
+- Schema output cleanup only deletes JSON carrying vovk's own `$schema` id ([9816dda](https://github.com/finom/vovk/commit/9816dda4))
+- A fetched schema's `segmentName` is no longer trusted as a write path ([d93a240](https://github.com/finom/vovk/commit/d93a240c))
+- `vovk init` only spawns a known package manager, never a path from `packageManager` ([053cb1a](https://github.com/finom/vovk/commit/053cb1a8))
+- `--prebundle-out-dir` takes effect and stays inside the project ([22f505c](https://github.com/finom/vovk/commit/22f505c6))
+- `vovk new segment` scaffolds `force-static` for static segments ([#25](https://github.com/finom/vovk/pull/25))
+
+### Upgrading from 0.2.x
+
+1. Remove `vovk-client` from your dependencies and import from `@/client` (or a relative path to the configured `outDir`).
+2. Replace `fromTemplates: ['js']` and friends with `['ts']`.
+3. Install `prettier` yourself if you want the client formatted, or set `prettifyClient: false`.
+4. Add the composed client output directory to `.gitignore`; `vovk init` does this for new projects.
+5. A stale `node_modules/.vovk-client` is inert and can be deleted.

package/client-templates/schema-ts/schema.ts.ejs

@@ -24,5 +24,5 @@ export const schema = {
   meta,
 };
 <% if (t.hasMixins) { %>
-export { Mixins };
+export type { Mixins };
 <% } %>

package/client-templates/ts-base/index.ts.ejs

@@ -23,5 +23,5 @@ export const <%= rpcModuleName %> = createRPC<<%= segment.segmentType === 'mixin
 }) %>
 export { schema };
 <% if (t.hasMixins) { %>
-export { Mixins };
+export type { Mixins };
 <% } %>

package/dist/bundle/index.mjs

@@ -1,5 +1,5 @@
-import path from 'node:path';
 import fs from 'node:fs/promises';
+import path from 'node:path';
 import groupBy from 'lodash/groupBy.js';
 import { generate } from '../generate/generate.mjs';
 import { BuiltInTemplateName } from '../get-project-info/get-config/get-template-defs.mjs';
@@ -9,46 +9,32 @@ export async function bundle({ projectInfo, fullSchema, cliBundleOptions, }) {
     const { config, log, cwd, apiDirAbsolutePath } = projectInfo;
     const locatedSegments = await locateSegments({ dir: apiDirAbsolutePath, config, log });
     const { bundle: bundleConfig } = config;
+    if (bundleConfig.build.isMissingBuild) {
+        throw new Error('No bundle.build function specified in the config. See https://vovk.dev/bundle for details.');
+    }
     const keepPrebundleDir = cliBundleOptions?.keepPrebundleDir ?? bundleConfig?.keepPrebundleDir ?? false;
-    const prebundleOutDirAbsolute = path.resolve(cwd, cliBundleOptions?.prebundleOutDir ?? bundleConfig.prebundleOutDir);
+    const prebundleOutDir = cliBundleOptions?.prebundleOutDir ?? bundleConfig.prebundleOutDir;
+    const prebundleOutDirAbsolute = path.resolve(cwd, prebundleOutDir);
+    // this directory gets removed recursively, so it must be a directory of our own inside the project
+    const relativeToCwd = path.relative(cwd, prebundleOutDirAbsolute);
+    const escapesCwd = relativeToCwd === '..' || relativeToCwd.startsWith(`..${path.sep}`);
+    if (!relativeToCwd || escapesCwd || path.isAbsolute(relativeToCwd)) {
+        throw new Error(`Invalid prebundle output directory ${JSON.stringify(prebundleOutDir)}. It is deleted after bundling, so it must be a subdirectory of the project, such as "tmp_prebundle".`);
+    }
     const entry = path.join(prebundleOutDirAbsolute, 'index.ts');
     const outDir = cliBundleOptions?.outDir ?? bundleConfig.outDir;
     if (!outDir) {
         throw new Error('No output directory specified for bundling');
     }
+    // CLI options win as a pair so config exclude cannot conflict with CLI include
+    const [includeSegments, excludeSegments] = cliBundleOptions.includeSegments?.length || cliBundleOptions.excludeSegments?.length
+        ? [cliBundleOptions.includeSegments, cliBundleOptions.excludeSegments]
+        : [bundleConfig.includeSegments, bundleConfig.excludeSegments];
+    if (includeSegments?.length && excludeSegments?.length) {
+        throw new Error('Both includeSegments and excludeSegments are set for the bundle. Please use only one of them.');
+    }
     const outDirAbsolute = path.resolve(cwd, outDir);
-    await generate({
-        isEnsuringClient: false,
-        isBundle: true,
-        projectInfo,
-        forceNothingWrittenLog: true,
-        fullSchema,
-        locatedSegments,
-        cliGenerateOptions: {
-            schemaPath: cliBundleOptions?.schemaPath,
-            origin: cliBundleOptions?.origin,
-            openapiSpec: cliBundleOptions?.openapiSpec,
-            openapiGetModuleName: cliBundleOptions?.openapiGetModuleName,
-            openapiGetMethodName: cliBundleOptions?.openapiGetMethodName,
-            openapiRootUrl: cliBundleOptions?.openapiRootUrl,
-            openapiMixinName: cliBundleOptions?.openapiMixinName,
-            openapiFallback: cliBundleOptions?.openapiFallback,
-            composedFrom: [BuiltInTemplateName.tsBase],
-            composedOut: prebundleOutDirAbsolute,
-            composedOnly: true,
-            composedIncludeSegments: cliBundleOptions.includeSegments ?? bundleConfig.includeSegments,
-            composedExcludeSegments: cliBundleOptions.excludeSegments ?? bundleConfig.excludeSegments,
-        },
-    });
-    log.debug(`Bundling ${chalkHighlightThing(entry)} to ${chalkHighlightThing(outDirAbsolute)}`);
-    await bundleConfig.build({
-        outDir: outDirAbsolute,
-        prebundleDir: prebundleOutDirAbsolute,
-        entry,
-    });
-    log.debug(`Bundled index.ts to ${chalkHighlightThing(outDirAbsolute)}`);
-    const requiresGroup = groupBy(Object.entries(bundleConfig.requires), ([, relativePath]) => relativePath);
-    for (const [relativePath, group] of Object.entries(requiresGroup)) {
+    try {
         await generate({
             isEnsuringClient: false,
             isBundle: true,
@@ -59,18 +45,54 @@ export async function bundle({ projectInfo, fullSchema, cliBundleOptions, }) {
             cliGenerateOptions: {
                 schemaPath: cliBundleOptions?.schemaPath,
                 origin: cliBundleOptions?.origin,
-                composedFrom: group.map(([templateName]) => templateName),
-                composedOut: path.resolve(outDirAbsolute, relativePath),
+                openapiSpec: cliBundleOptions?.openapiSpec,
+                openapiGetModuleName: cliBundleOptions?.openapiGetModuleName,
+                openapiGetMethodName: cliBundleOptions?.openapiGetMethodName,
+                openapiRootUrl: cliBundleOptions?.openapiRootUrl,
+                openapiMixinName: cliBundleOptions?.openapiMixinName,
+                openapiFallback: cliBundleOptions?.openapiFallback,
+                composedFrom: [BuiltInTemplateName.tsBase],
+                composedOut: prebundleOutDirAbsolute,
                 composedOnly: true,
+                composedIncludeSegments: includeSegments,
+                composedExcludeSegments: excludeSegments,
             },
         });
+        log.debug(`Bundling ${chalkHighlightThing(entry)} to ${chalkHighlightThing(outDirAbsolute)}`);
+        await bundleConfig.build({
+            outDir: outDirAbsolute,
+            prebundleDir: prebundleOutDirAbsolute,
+            entry,
+        });
+        log.debug(`Bundled index.ts to ${chalkHighlightThing(outDirAbsolute)}`);
+        const requiresGroup = groupBy(Object.entries(bundleConfig.requires), ([, relativePath]) => relativePath);
+        for (const [relativePath, group] of Object.entries(requiresGroup)) {
+            await generate({
+                isEnsuringClient: false,
+                isBundle: true,
+                projectInfo,
+                forceNothingWrittenLog: true,
+                fullSchema,
+                locatedSegments,
+                cliGenerateOptions: {
+                    schemaPath: cliBundleOptions?.schemaPath,
+                    origin: cliBundleOptions?.origin,
+                    composedFrom: group.map(([templateName]) => templateName),
+                    composedOut: path.resolve(outDirAbsolute, relativePath),
+                    composedOnly: true,
+                },
+            });
+        }
     }
-    if (!keepPrebundleDir) {
-        await fs.rm(prebundleOutDirAbsolute, { recursive: true, force: true });
-        log.debug(`Deleted temporary TypeScript client output directory: ${chalkHighlightThing(prebundleOutDirAbsolute)}`);
-    }
-    else {
-        log.debug(`Temporary TypeScript client output directory not deleted because it is marked to keep: ${chalkHighlightThing(prebundleOutDirAbsolute)}`);
+    finally {
+        // clean up the prebundle dir even when generation or build fails
+        if (!keepPrebundleDir) {
+            await fs.rm(prebundleOutDirAbsolute, { recursive: true, force: true });
+            log.debug(`Deleted temporary TypeScript client output directory: ${chalkHighlightThing(prebundleOutDirAbsolute)}`);
+        }
+        else {
+            log.debug(`Temporary TypeScript client output directory not deleted because it is marked to keep: ${chalkHighlightThing(prebundleOutDirAbsolute)}`);
+        }
     }
     log.info(`Bundled TypeScript client to ${chalkHighlightThing(outDirAbsolute)}`);
 }

package/dist/dev/diff-segment-schema.d.mts

@@ -15,22 +15,5 @@ export interface DiffResult {
 }
 export declare function diffHandlers<T extends VovkControllerSchema['handlers']>(oldHandlers: T, newHandlers: T, nameOfClass: string): HandlersDiff;
 export declare function diffControllers<T extends VovkSegmentSchema['controllers']>(oldItems: T, newItems: T): ControllersDiff;
-/**
-example output:
-{
-  controllers: {
-    added: ["ControllerC"],
-    removed: ["ControllerB"],
-    handlers: [
-      {
-        nameOfClass: "ControllerA",
-        added: ["handlerF"],
-        removed: [],
-        changed: ["handlerD"]
-      }
-    ]
-  }
-}
-*/
 export declare function diffSegmentSchema(oldJson: VovkSegmentSchema, newJson: VovkSegmentSchema): DiffResult;
 export {};

package/dist/dev/diff-segment-schema.mjs

@@ -40,23 +40,7 @@ export function diffControllers(oldItems, newItems) {
     }
     return { added, removed, handlers: handlersDiff };
 }
-/**
-example output:
-{
-  controllers: {
-    added: ["ControllerC"],
-    removed: ["ControllerB"],
-    handlers: [
-      {
-        nameOfClass: "ControllerA",
-        added: ["handlerF"],
-        removed: [],
-        changed: ["handlerD"]
-      }
-    ]
-  }
-}
-*/
+// returns e.g. { controllers: { added: [...], removed: [...], handlers: [{ nameOfClass, added, removed, changed }] } }
 export function diffSegmentSchema(oldJson, newJson) {
     return {
         controllers: diffControllers(oldJson.controllers ?? {}, newJson.controllers ?? {}),

package/dist/dev/ensure-schema-files.mjs

@@ -2,9 +2,9 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import debounce from 'lodash/debounce.js';
 import { VovkSchemaIdEnum } from 'vovk/internal';
-import { writeOneSegmentSchemaFile, META_FILE_NAME, ROOT_SEGMENT_FILE_NAME } from './write-one-segment-schema-file.mjs';
 import { formatLoggedSegmentName } from '../utils/format-logged-segment-name.mjs';
 import { writeMetaJson } from './write-meta-json.mjs';
+import { META_FILE_NAME, ROOT_SEGMENT_FILE_NAME, writeOneSegmentSchemaFile } from './write-one-segment-schema-file.mjs';
 /**
  * Ensure that the schema files are created to avoid any import errors.
  */
@@ -31,20 +31,34 @@ export async function ensureSchemaFiles(projectInfo, schemaOutAbsolutePath, segm
             hasChanged = true;
         }
     }));
-    // Recursive function to delete unnecessary JSON files and folders
+    // only a file carrying the vovk $schema id is ours to delete
+    async function isVovkSchemaFile(absolutePath) {
+        try {
+            const parsed = JSON.parse(await fs.readFile(absolutePath, 'utf-8'));
+            return typeof parsed.$schema === 'string' && parsed.$schema.startsWith('https://vovk.dev/api/schema/');
+        }
+        catch {
+            return false;
+        }
+    }
+    // Recursive function to delete unnecessary JSON files and folders, returns true if anything was deleted
     async function deleteUnnecessaryJsonFiles(dirPath, allow = [`${META_FILE_NAME}.json`]) {
         const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        let hasDeleted = false;
         await Promise.all(entries.map(async (entry) => {
             const absolutePath = path.join(dirPath, entry.name);
             if (entry.isDirectory()) {
                 // Recursively delete unnecessary files and folders within nested directories
-                await deleteUnnecessaryJsonFiles(absolutePath);
-                // Check if the directory is empty after deletion and remove it if so
-                const remainingEntries = await fs.readdir(absolutePath);
-                if (remainingEntries.length === 0) {
-                    await fs.rmdir(absolutePath);
-                    projectInfo?.log.debug(`Deleted unnecessary schema directory "${absolutePath}"`);
-                    hasChanged = true;
+                const deletedInside = await deleteUnnecessaryJsonFiles(absolutePath);
+                // remove the directory only when this cleanup emptied it, a pre-existing empty dir is not ours
+                if (deletedInside) {
+                    const remainingEntries = await fs.readdir(absolutePath);
+                    if (remainingEntries.length === 0) {
+                        await fs.rmdir(absolutePath);
+                        projectInfo?.log.debug(`Deleted unnecessary schema directory "${absolutePath}"`);
+                        hasChanged = true;
+                        hasDeleted = true;
+                    }
                 }
             }
             else if (entry.isFile() && entry.name.endsWith('.json')) {
@@ -52,13 +66,17 @@ export async function ensureSchemaFiles(projectInfo, schemaOutAbsolutePath, segm
                 const segmentName = relativePath.replace(/\\/g, '/').slice(0, -5); // Remove '.json' extension
                 if (!segmentNames.includes(segmentName) &&
                     !segmentNames.includes(segmentName.replace(ROOT_SEGMENT_FILE_NAME, '')) &&
-                    !allow.includes(entry.name)) {
+                    !allow.includes(entry.name) &&
+                    // never delete a json file vovk did not write, schemaOutDir may point at user dirs
+                    (await isVovkSchemaFile(absolutePath))) {
                     await fs.unlink(absolutePath);
                     projectInfo?.log.debug(`Deleted unnecessary schema file for ${formatLoggedSegmentName(segmentName)}`);
                     hasChanged = true;
+                    hasDeleted = true;
                 }
             }
         }));
+        return hasDeleted;
     }
     await deleteUnnecessaryJsonFiles(schemaOutAbsolutePath);
     if (hasChanged)

package/dist/dev/index.mjs

@@ -1,25 +1,25 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { VovkSchemaIdEnum } from 'vovk/internal';
 import * as chokidar from 'chokidar';
-import { Agent, setGlobalDispatcher } from 'undici';
-import keyBy from 'lodash/keyBy.js';
 import capitalize from 'lodash/capitalize.js';
 import debounce from 'lodash/debounce.js';
-import once from 'lodash/once.js';
 import isEmpty from 'lodash/isEmpty.js';
-import { ensureSchemaFiles, debouncedEnsureSchemaFiles } from './ensure-schema-files.mjs';
-import { writeOneSegmentSchemaFile } from './write-one-segment-schema-file.mjs';
-import { logDiffResult } from './log-diff-result.mjs';
+import keyBy from 'lodash/keyBy.js';
+import once from 'lodash/once.js';
+import { Agent, setGlobalDispatcher } from 'undici';
+import { VovkSchemaIdEnum } from 'vovk/internal';
 import { ensureClient } from '../generate/ensure-client.mjs';
-import { getProjectInfo } from '../get-project-info/index.mjs';
 import { generate } from '../generate/generate.mjs';
-import { locateSegments } from '../utils/locate-segments.mjs';
+import { getMetaSchema } from '../get-project-info/get-meta-schema.mjs';
+import { getProjectInfo } from '../get-project-info/index.mjs';
+import { chalkHighlightThing } from '../utils/chalk-highlight-thing.mjs';
 import { debounceWithArgs } from '../utils/debounce-with-args.mjs';
 import { formatLoggedSegmentName } from '../utils/format-logged-segment-name.mjs';
+import { locateSegments } from '../utils/locate-segments.mjs';
+import { debouncedEnsureSchemaFiles, ensureSchemaFiles } from './ensure-schema-files.mjs';
+import { logDiffResult } from './log-diff-result.mjs';
 import { writeMetaJson } from './write-meta-json.mjs';
-import { chalkHighlightThing } from '../utils/chalk-highlight-thing.mjs';
-import { getMetaSchema } from '../get-project-info/get-meta-schema.mjs';
+import { writeOneSegmentSchemaFile } from './write-one-segment-schema-file.mjs';
 export class VovkDev {
     #projectInfo;
     #segments = [];
@@ -33,7 +33,8 @@ export class VovkDev {
     #logLevel;
     constructor({ schemaOut, devHttps, logLevel }) {
         this.#schemaOut = schemaOut || null;
-        this.#devHttps = devHttps || false;
+        // null when the flag is omitted so config.devHttps can take effect
+        this.#devHttps = devHttps ?? null;
         this.#logLevel = logLevel || 'info';
     }
     #watchSegments = (callback) => {
@@ -304,6 +305,11 @@ export class VovkDev {
             return;
         }
         log.debug(`Handling received schema from ${formatLoggedSegmentName(segmentName)}`);
+        // the write path is built from segmentName, an http response must not name a different segment
+        if ((segmentSchema.segmentName ?? '') !== segmentName) {
+            log.error(`Schema for ${formatLoggedSegmentName(segmentName)} reported a different segment name ${JSON.stringify(segmentSchema.segmentName)}, ignoring it`);
+            return;
+        }
         const schemaOutAbsolutePath = path.resolve(cwd, this.#schemaOut ?? config.schemaOutDir);
         const segment = this.#segments.find((s) => s.segmentName === segmentName);
         if (!segment) {
@@ -402,7 +408,7 @@ const env = process.env;
 if (env.__VOVK_START_WATCHER_IN_STANDALONE_MODE__ === 'true') {
     void new VovkDev({
         schemaOut: env.__VOVK_SCHEMA_OUT_FLAG__ || undefined,
-        devHttps: env.__VOVK_DEV_HTTPS_FLAG__ === 'true',
+        devHttps: env.__VOVK_DEV_HTTPS_FLAG__ === 'true' || undefined,
         logLevel: env.__VOVK_LOG_LEVEL__,
     }).start({
         exit: env.__VOVK_EXIT__ === 'true',

package/dist/dev/log-diff-result.d.mts

@@ -1,3 +1,3 @@
-import type { DiffResult } from './diff-segment-schema.mjs';
 import type { ProjectInfo } from '../get-project-info/index.mjs';
+import type { DiffResult } from './diff-segment-schema.mjs';
 export declare function logDiffResult(segmentName: string, diffResult: DiffResult, projectInfo: ProjectInfo): void;

package/dist/dev/log-diff-result.mjs

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
-import { formatLoggedSegmentName } from '../utils/format-logged-segment-name.mjs';
 import { chalkHighlightThing } from '../utils/chalk-highlight-thing.mjs';
+import { formatLoggedSegmentName } from '../utils/format-logged-segment-name.mjs';
 export function logDiffResult(segmentName, diffResult, projectInfo) {
     const diffNormalized = [];
     diffResult.controllers.added.forEach((name) => {

package/dist/dev/write-meta-json.mjs

@@ -1,8 +1,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { META_FILE_NAME } from './write-one-segment-schema-file.mjs';
-import { chalkHighlightThing } from '../utils/chalk-highlight-thing.mjs';
 import { getMetaSchema } from '../get-project-info/get-meta-schema.mjs';
+import { chalkHighlightThing } from '../utils/chalk-highlight-thing.mjs';
+import { META_FILE_NAME } from './write-one-segment-schema-file.mjs';
 export async function writeMetaJson(schemaOutAbsolutePath, projectInfo) {
     const metaJsonPath = path.join(schemaOutAbsolutePath, `${META_FILE_NAME}.json`);
     const metaStr = JSON.stringify(getMetaSchema({

package/dist/dev/write-one-segment-schema-file.mjs

@@ -1,11 +1,16 @@
-import path from 'node:path';
 import fs from 'node:fs/promises';
-import { diffSegmentSchema } from './diff-segment-schema.mjs';
+import path from 'node:path';
 import { getFileSystemEntryType } from '../utils/get-file-system-entry-type.mjs';
+import { diffSegmentSchema } from './diff-segment-schema.mjs';
 export const ROOT_SEGMENT_FILE_NAME = 'root';
 export const META_FILE_NAME = '_meta';
 export async function writeOneSegmentSchemaFile({ schemaOutAbsolutePath, segmentSchema, skipIfExists = false, }) {
     const segmentPath = path.join(schemaOutAbsolutePath, `${segmentSchema.segmentName || ROOT_SEGMENT_FILE_NAME}.json`);
+    // segmentName may come from an http response, keep the write inside the schema out dir
+    const relativeToOut = path.relative(schemaOutAbsolutePath, segmentPath);
+    if (relativeToOut.startsWith(`..${path.sep}`) || relativeToOut === '..' || path.isAbsolute(relativeToOut)) {
+        throw new Error(`Refusing to write schema outside ${schemaOutAbsolutePath} for segment ${JSON.stringify(segmentSchema.segmentName)}`);
+    }
     if (skipIfExists && (await getFileSystemEntryType(segmentPath))) {
         try {
             await fs.stat(segmentPath);

package/dist/generate/ensure-client.mjs

@@ -1,6 +1,6 @@
 import { VovkSchemaIdEnum } from 'vovk/internal';
-import { generate } from './generate.mjs';
 import { getMetaSchema } from '../get-project-info/get-meta-schema.mjs';
+import { generate } from './generate.mjs';
 const getEmptySegmentRecordSchema = (segmentNames) => {
     const result = {};
     for (const segmentName of segmentNames) {

package/dist/generate/generate.mjs

@@ -1,40 +1,48 @@
-import path from 'node:path';
 import fs from 'node:fs/promises';
+import path from 'node:path';
+import { getTsconfig } from 'get-tsconfig';
 import matter from 'gray-matter';
 import _ from 'lodash';
 import { openAPIToVovkSchema, vovkSchemaToOpenAPI } from 'vovk/internal';
-import { getClientTemplateFiles } from './get-client-template-files.mjs';
+import { ROOT_SEGMENT_FILE_NAME } from '../dev/write-one-segment-schema-file.mjs';
+import { BuiltInTemplateName } from '../get-project-info/get-config/get-template-defs.mjs';
 import { chalkHighlightThing } from '../utils/chalk-highlight-thing.mjs';
+import { normalizeOpenAPIMixin } from '../utils/normalize-openapi-mixin.mjs';
 import { pickSegmentFullSchema } from '../utils/pick-segment-full-schema.mjs';
 import { removeUnlistedDirectories } from '../utils/remove-unlisted-directories.mjs';
-import { writeOneClientFile, normalizeOutTemplatePath } from './write-one-client-file.mjs';
-import { ROOT_SEGMENT_FILE_NAME } from '../dev/write-one-segment-schema-file.mjs';
-import { getTsconfig } from 'get-tsconfig';
-import { normalizeOpenAPIMixin } from '../utils/normalize-openapi-mixin.mjs';
-import { BuiltInTemplateName } from '../get-project-info/get-config/get-template-defs.mjs';
+import { getClientTemplateFiles } from './get-client-template-files.mjs';
+import { normalizeOutTemplatePath, writeOneClientFile } from './write-one-client-file.mjs';
 const getIncludedSegmentNames = (config, fullSchema, configKey, cliGenerateOptions) => {
     const segments = Object.values(fullSchema.segments);
-    const includeSegments = cliGenerateOptions?.[configKey === 'segmentedClient' ? 'segmentedIncludeSegments' : 'composedIncludeSegments'] ??
-        config[configKey].includeSegments;
-    const excludeSegments = cliGenerateOptions?.[configKey === 'segmentedClient' ? 'segmentedExcludeSegments' : 'composedExcludeSegments'] ??
-        config[configKey].excludeSegments;
+    const cliIncludeSegments = cliGenerateOptions?.[configKey === 'segmentedClient' ? 'segmentedIncludeSegments' : 'composedIncludeSegments'];
+    const cliExcludeSegments = cliGenerateOptions?.[configKey === 'segmentedClient' ? 'segmentedExcludeSegments' : 'composedExcludeSegments'];
+    // CLI options win as a pair so config exclude cannot conflict with CLI include
+    const isFromCli = !!(cliIncludeSegments?.length || cliExcludeSegments?.length);
+    const includeSegments = isFromCli ? cliIncludeSegments : config[configKey].includeSegments;
+    const excludeSegments = isFromCli ? cliExcludeSegments : config[configKey].excludeSegments;
     if (includeSegments?.length && excludeSegments?.length) {
-        throw new Error(`Both includeSegments and excludeSegments are set in "${configKey}" config. Please use only one of them.`);
+        throw new Error(`Both includeSegments and excludeSegments are set ${isFromCli ? 'as CLI options' : `in "${configKey}" config`}. Please use only one of them.`);
     }
-    const includedSegmentNames = Array.isArray(includeSegments) && includeSegments.length
-        ? includeSegments.map((segmentName) => {
-            const segment = segments.find(({ segmentName: sName }) => sName === segmentName);
-            if (!segment) {
+    const segmentExists = (segmentName) => segments.some(({ segmentName: sName }) => sName === segmentName);
+    if (includeSegments?.length) {
+        for (const segmentName of includeSegments) {
+            if (!segmentExists(segmentName)) {
                 throw new Error(`Segment "${segmentName}" not found in the config for "${configKey}"`);
             }
-            return segment.segmentName;
-        })
-        : Array.isArray(excludeSegments) && excludeSegments.length // TODO: Warn if excludeSegments includes a segment name that is not listed at segments
-            ? segments
-                .filter(({ segmentName }) => !excludeSegments?.includes(segmentName))
-                .map(({ segmentName }) => segmentName)
-            : segments.map(({ segmentName }) => segmentName);
-    return includedSegmentNames;
+        }
+        return includeSegments;
+    }
+    if (excludeSegments?.length) {
+        for (const segmentName of excludeSegments) {
+            if (!segmentExists(segmentName)) {
+                throw new Error(`Segment "${segmentName}" from excludeSegments not found in the config for "${configKey}"`);
+            }
+        }
+        return segments
+            .filter(({ segmentName }) => !excludeSegments.includes(segmentName))
+            .map(({ segmentName }) => segmentName);
+    }
+    return segments.map(({ segmentName }) => segmentName);
 };
 function logClientGenerationResults({ results, log, isEnsuringClient = false, forceNothingWrittenLog = false, clientType = 'Composed', startTime, fromTemplates, }) {
     const writtenResults = results.filter(({ written }) => written);
@@ -221,6 +229,8 @@ export async function generate({ isEnsuringClient = false, isBundle = false, pro
             cliGenerateOptions,
             configKey: 'segmentedClient',
         });
+        // what a generated file may look like inside a segment directory, used to spare user files when pruning
+        const generatedRelPaths = segmentedClientTemplateFiles.map(({ templateFilePath, relativeDir }) => path.join(relativeDir, path.basename(templateFilePath).replace(/\.ejs$/, '')));
         const segmentedClientResults = await Promise.all(segmentedClientTemplateFiles.map(async (clientTemplateFile) => {
             const { templateFilePath, templateName, templateDef, outCwdRelativeDir } = clientTemplateFile;
             const templateContent = await fs.readFile(templateFilePath, 'utf-8');
@@ -280,7 +290,10 @@ export async function generate({ isEnsuringClient = false, isBundle = false, pro
             }));
             const outAbsoluteDir = path.resolve(cwd, outCwdRelativeDir);
             // Remove unlisted directories in the output directory
-            await removeUnlistedDirectories(outAbsoluteDir, segmentNames.map((s) => s || ROOT_SEGMENT_FILE_NAME));
+            const skippedDirs = await removeUnlistedDirectories(outAbsoluteDir, segmentNames.map((s) => s || ROOT_SEGMENT_FILE_NAME), generatedRelPaths);
+            for (const skippedDir of skippedDirs) {
+                log.warn(`Directory ${chalkHighlightThing(skippedDir)} is not a known segment but holds files that were not generated, so it is left untouched.`);
+            }
             return {
                 written: results.filter((result) => !!result).some(({ written }) => written),
                 templateName,

package/dist/generate/get-client-template-files.mjs

@@ -1,10 +1,10 @@
 import path from 'node:path';
 import { glob } from 'glob';
-import { resolveAbsoluteModulePath } from '../utils/resolve-absolute-module-path.mjs';
-import { getFileSystemEntryType, FileSystemEntryType } from '../utils/get-file-system-entry-type.mjs';
-import { getPublicModuleNameFromPath } from '../utils/get-public-module-name-from-path.mjs';
-import omit from 'lodash/omit.js';
 import merge from 'lodash/merge.js';
+import omit from 'lodash/omit.js';
+import { FileSystemEntryType, getFileSystemEntryType } from '../utils/get-file-system-entry-type.mjs';
+import { getPublicModuleNameFromPath } from '../utils/get-public-module-name-from-path.mjs';
+import { resolveAbsoluteModulePath } from '../utils/resolve-absolute-module-path.mjs';
 export async function getClientTemplateFiles({ config, cwd, log, configKey, cliGenerateOptions, }) {
     const usedTemplateDefs = {};
     const fromTemplates = configKey === 'composedClient'
@@ -18,6 +18,10 @@ export async function getClientTemplateFiles({ config, cwd, log, configKey, cliG
     const configOutDir = config[configKey].outDir;
     for (const templateName of fromTemplates) {
         if (!(templateName in config.clientTemplateDefs)) {
+            // js family removed in v4
+            if (['js', 'jsBase', 'schemaJs', 'openapiJs'].includes(templateName)) {
+                throw new Error(`The "${templateName}" template was removed in v4. Use "ts" instead.`);
+            }
             throw new Error(`Unknown template name: ${templateName}`);
         }
         usedTemplateDefs[templateName] = config.clientTemplateDefs[templateName];

package/dist/generate/get-project-full-schema.d.mts

@@ -1,6 +1,6 @@
 import type { VovkSchema } from 'vovk';
-import type { ProjectInfo } from '../get-project-info/index.mjs';
 import { type VovkStrictConfig } from 'vovk/internal';
+import type { ProjectInfo } from '../get-project-info/index.mjs';
 export declare function getProjectFullSchema({ schemaOutAbsolutePath, isNextInstalled, log, config, }: {
     schemaOutAbsolutePath: string;
     isNextInstalled: boolean;

package/dist/generate/get-project-full-schema.mjs

@@ -1,9 +1,9 @@
-import { readFile, access } from 'node:fs/promises';
+import { access, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { glob } from 'glob';
+import { deepExtend, VovkSchemaIdEnum } from 'vovk/internal';
 import { META_FILE_NAME, ROOT_SEGMENT_FILE_NAME } from '../dev/write-one-segment-schema-file.mjs';
 import { getMetaSchema } from '../get-project-info/get-meta-schema.mjs';
-import { deepExtend, VovkSchemaIdEnum } from 'vovk/internal';
 export async function getProjectFullSchema({ schemaOutAbsolutePath, isNextInstalled, log, config, }) {
     const result = {
         $schema: VovkSchemaIdEnum.SCHEMA,

package/dist/generate/index.d.mts

@@ -1,6 +1,6 @@
 import type { VovkSchema } from 'vovk';
-import type { GenerateOptions } from '../types.mjs';
 import type { ProjectInfo } from '../get-project-info/index.mjs';
+import type { GenerateOptions } from '../types.mjs';
 export declare class VovkGenerate {
     #private;
     constructor({ cliGenerateOptions, projectInfo, forceNothingWrittenLog, }: {
@@ -8,7 +8,7 @@ export declare class VovkGenerate {
         projectInfo: ProjectInfo;
         forceNothingWrittenLog?: boolean;
     });
-    start(): void;
+    start(): Promise<void> | undefined;
     generate(): Promise<void>;
     getFullSchema(): Promise<VovkSchema>;
     watch({ throttleDelay }: {