@amritk/mjst 0.13.9 → 0.14.8

package/dist/help-text.d.ts

@@ -4,4 +4,4 @@
  * documents these flags (config.schema.json) is not shipped in the published
  * package; the help-text test cross-checks that every flag is listed.
  */
-export declare const HELP_TEXT = "mjst \u2014 generate TypeScript parsers and type definitions from JSON Schemas\n\nUsage:\n  mjst --schema <path> --out-dir <dir> [options]\n  mjst --schema-dir <dir> --out-dir <dir> [options]\n  mjst --schema <path> --out-file <file> --types-only [options]\n\nSubcommands (each with its own flags and --help):\n  mjst lint <files>                       Lint JSON/YAML documents against a ruleset\n  mjst compile-api <module> --out <file>  Compile @amritk/api route contracts into a fetch-handler module\n\nInput:\n  --schema <path>       Schema to process: a JSON Schema file, or a module when --input is set\n  --schema-dir <dir>    Directory of JSON Schemas, processed recursively (instead of --schema)\n  --input <format>      Schema source format: json (default), typebox, zod, valibot, effect\n  --export <name>       Which export of the schema module to use when --input is not json\n\nOutput:\n  --out-dir <dir>       Output directory for the generated files\n  --out-file <file>     Single-file output instead of a directory (requires --types-only)\n  --types-only          Generate type definitions only, without parser functions\n  --validators          Also emit validateX/isX validators into a validators/ subdir\n  --examples            Also emit fast-check arbitraries + example values under examples/\n  --build               Compile the generated files to .js/.d.ts (implies --import-ext js)\n  --import-ext <ext>    Extension on generated relative imports: ts (default) or js\n  --helpers <mode>      Runtime helpers: package or embedded (default: auto-detect from package.json)\n  --root-type <name>    Root type name for a single --schema run (default: schema title or filename)\n  --type-suffix <s>     Suffix appended to every $ref-derived type name\n  --banner [text]       Prepend a header comment to every generated file\n  --readonly            Emit deeply readonly type definitions\n\nValidation:\n  --strict              Throw on type/shape mismatches instead of coercing to defaults\n  --strip-unknown       Silently drop undeclared input keys at every nesting level\n  --case-insensitive    Normalize mis-cased enum/const strings to their exact casing\n  --log-warnings        console.warn on input keys not declared in the schema\n\nReference resolution:\n  --resolve-remote      Fetch http(s) $refs while resolving cross-file/remote refs (off by default)\n  --allowed-hosts <h>   Restrict remote $ref fetches to these hosts (comma-separated; implies --resolve-remote)\n  --allow-private-hosts Permit remote $refs to private/loopback hosts (SSRF guard, off by default)\n\nMisc:\n  --config <path>       JSON config file with the same keys; CLI flags take precedence\n  --version, -v         Print the CLI version\n  --help, -h            Print this help\n\nDocs: https://github.com/amritk/mjst/tree/main/packages/cli#readme\n";
+export declare const HELP_TEXT = "mjst \u2014 generate TypeScript parsers and type definitions from JSON Schemas\n\nUsage:\n  mjst --schema <path> --out-dir <dir> [options]\n  mjst --schema-dir <dir> --out-dir <dir> [options]\n  mjst --schema <path> --out-file <file> --types-only [options]\n\nSubcommands (each with its own flags and --help):\n  mjst lint <files>                       Lint JSON/YAML documents against a ruleset\n  mjst compile-api <module> --out <file>  Compile @amritk/api route contracts into a fetch-handler module\n\nInput:\n  --schema <path>       Schema to process: a JSON Schema file, or a module when --input is set\n  --schema-dir <dir>    Directory of JSON Schemas, processed recursively (instead of --schema)\n  --input <format>      Schema source format: json (default), typebox, zod, valibot, effect\n  --export <name>       Which export of the schema module to use when --input is not json\n\nOutput:\n  --out-dir <dir>       Output directory for the generated files\n  --out-file <file>     Single-file output instead of a directory (requires --types-only)\n  --types-only          Generate type definitions only, without parser functions\n  --validators          Also emit validateX/isX validators into a validators/ subdir\n  --examples            Also emit fast-check arbitraries + example values under examples/\n  --build               Compile the generated files to .js/.d.ts (implies --import-ext js)\n  --force               Overwrite pre-existing files in the output destination\n  --import-ext <ext>    Extension on generated relative imports: ts (default) or js\n  --helpers <mode>      Runtime helpers: package or embedded (default: auto-detect from package.json)\n  --root-type <name>    Root type name for a single --schema run (default: schema title or filename)\n  --type-suffix <s>     Suffix appended to every $ref-derived type name\n  --banner [text]       Prepend a header comment to every generated file\n  --readonly            Emit deeply readonly type definitions\n\nValidation:\n  --strict              Throw on type/shape mismatches instead of coercing to defaults\n  --strip-unknown       Silently drop undeclared input keys at every nesting level\n  --case-insensitive    Normalize mis-cased enum/const strings to their exact casing\n  --log-warnings        console.warn on input keys not declared in the schema\n\nReference resolution:\n  --resolve-remote      Fetch http(s) $refs while resolving cross-file/remote refs (off by default)\n  --allowed-hosts <h>   Restrict remote $ref fetches to these hosts (comma-separated; implies --resolve-remote)\n  --allow-private-hosts Permit remote $refs to private/loopback hosts (SSRF guard, off by default)\n  --allowed-roots <d>   Extra directories a local $ref may resolve into, on top of the schema's own\n                        (comma-separated; relative to the current directory)\n\nMisc:\n  --config <path>       JSON config file with the same keys; CLI flags take precedence\n  --version, -v         Print the CLI version\n  --help, -h            Print this help\n\nDocs: https://github.com/amritk/mjst/tree/main/packages/cli#readme\n";

package/dist/help-text.js

@@ -22,6 +22,7 @@ Output:
   --validators          Also emit validateX/isX validators into a validators/ subdir
   --examples            Also emit fast-check arbitraries + example values under examples/
   --build               Compile the generated files to .js/.d.ts (implies --import-ext js)
+  --force               Overwrite pre-existing files in the output destination
   --import-ext <ext>    Extension on generated relative imports: ts (default) or js
   --helpers <mode>      Runtime helpers: package or embedded (default: auto-detect from package.json)
   --root-type <name>    Root type name for a single --schema run (default: schema title or filename)
@@ -39,6 +40,8 @@ Reference resolution:
   --resolve-remote      Fetch http(s) $refs while resolving cross-file/remote refs (off by default)
   --allowed-hosts <h>   Restrict remote $ref fetches to these hosts (comma-separated; implies --resolve-remote)
   --allow-private-hosts Permit remote $refs to private/loopback hosts (SSRF guard, off by default)
+  --allowed-roots <d>   Extra directories a local $ref may resolve into, on top of the schema's own
+                        (comma-separated; relative to the current directory)
 
 Misc:
   --config <path>       JSON config file with the same keys; CLI flags take precedence

package/dist/lint/resolver.d.ts

@@ -10,6 +10,13 @@ export type ResolverOptions = {
     allowedHosts?: string[];
     /** Permit remote refs to private/loopback/link-local hosts (off by default as an SSRF guard). */
     allowPrivateHosts?: boolean;
+    /**
+     * Extra directories a local `$ref` may resolve into, on top of the linted
+     * document's own directory (which is always allowed). Empty by default, which
+     * keeps a `$ref` from walking out of the tree the document belongs to.
+     * Relative entries are resolved against the process working directory.
+     */
+    allowedRoots?: string[];
 };
 /**
  * Builds a {@link LintResolver} backed by `@amritk/resolve-refs`, dereferencing

package/dist/lint/resolver.js

@@ -1,9 +1,10 @@
 import { readFileSync } from "node:fs";
-import { resolve as resolvePath } from "node:path";
+import { dirname, resolve as resolvePath } from "node:path";
 import { createDocument, resolveSourceOriginFromMap } from "@amritk/lint";
 import { DiagnosticSeverity } from "@amritk/lint/types";
 import { resolveRefs, resolveRefsFromFile } from "@amritk/resolve-refs";
 import { parse as parseYaml } from "@amritk/yaml";
+import { withAllowedRootsHint } from "../allowed-roots-hint.js";
 import { hasExternalRefs } from "../has-external-refs.js";
 const isRemote = (location) => /^https?:\/\//i.test(location);
 const parseDoc = (content, location) => {
@@ -51,7 +52,7 @@ const toFindings = (errors, root) => errors.map((error) => {
   const location = error.path.length > 0 ? root.getLocationForJsonPath(error.path, true) : void 0;
   const finding = {
     code: "unresolved-ref",
-    message: error.message,
+    message: withAllowedRootsHint(error.message),
     path: error.path,
     severity: DiagnosticSeverity.Error,
     range: location?.range ?? DOCUMENT_START
@@ -68,12 +69,16 @@ const createLintResolver = (options = {}) => {
     parse: parseDoc,
     trackOrigins: true
   };
+  const extraRoots = (options.allowedRoots ?? []).map((root) => resolvePath(root));
   return async (document, { input }) => {
     const { source } = document;
     if (source && hasExternalRefs(document.data)) {
       const absolute = resolvePath(source);
       if (readsBackAs(absolute, input)) {
-        const { resolved: resolved2, origins: origins2, errors: errors2 } = await resolveRefsFromFile(absolute, fromFileOptions);
+        const { resolved: resolved2, origins: origins2, errors: errors2 } = await resolveRefsFromFile(absolute, {
+          ...fromFileOptions,
+          ...extraRoots.length > 0 ? { allowedRoots: [dirname(absolute), ...extraRoots] } : {}
+        });
         return {
           resolved: resolved2,
           sources: buildSourceSet(document, resolved2, origins2, absolute),

package/dist/lint/run.js

@@ -47,39 +47,65 @@ const mapWithConcurrency = async (items, limit, worker) => {
   await Promise.all(runners);
   return results;
 };
+const parseArgs = async (argv) => {
+  try {
+    const parsed = await yargs(argv).scriptName("lint").parserConfiguration({ "greedy-arrays": false }).strict().exitProcess(false).fail((message, error) => {
+      throw error ?? new Error(message);
+    }).usage("$0 [documents..]", "Lint JSON/YAML documents against a ruleset").positional("documents", { describe: "Documents or globs to lint", type: "string", array: true }).option("ruleset", { alias: "r", type: "string", describe: "Path to a ruleset file" }).option("encoding", { type: "string", default: "utf8", describe: "Input encoding" }).option("fail-severity", { alias: "F", type: "string", default: "error", choices: Object.keys(SEVERITY_BY_NAME) }).option("display-only-failures", { alias: "D", type: "boolean", default: false }).option("verbose", { type: "boolean", default: false }).option("quiet", { alias: "q", type: "boolean", default: false }).option("stdin-filepath", {
+      type: "string",
+      describe: "Path to associate with stdin input (labels findings and enables ruleset discovery)"
+    }).option("concurrency", {
+      type: "number",
+      default: 8,
+      describe: "Maximum number of documents to lint in parallel"
+    }).option("resolve", {
+      type: "boolean",
+      default: true,
+      describe: "Dereference $ref / $dynamicRef / $recursiveRef before linting (use --no-resolve to disable)"
+    }).option("resolve-remote", {
+      type: "boolean",
+      default: false,
+      describe: "Allow fetching http(s) $refs while resolving (off by default; a lint run stays offline)"
+    }).option("allowed-hosts", {
+      type: "string",
+      array: true,
+      describe: "Restrict remote $ref fetches to these hosts (implies --resolve-remote)"
+    }).option("allow-private-hosts", {
+      type: "boolean",
+      default: false,
+      describe: "Permit remote $refs to private/loopback hosts (SSRF guard, off by default)"
+    }).option("allowed-roots", {
+      type: "string",
+      array: true,
+      describe: "Extra directories a local $ref may resolve into, beyond the document's own (repeat the flag; relative to the current directory)"
+    }).help().alias("help", "h").parse();
+    if (!Number.isFinite(parsed.concurrency) || parsed.concurrency < 1) {
+      return { error: "Invalid --concurrency value. Expected a positive number." };
+    }
+    return { args: parsed };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+};
 const run = async (argv, options = {}) => {
   const out = [];
   const err = [];
-  const parsed = await yargs(argv).scriptName("lint").parserConfiguration({ "greedy-arrays": false }).usage("$0 [documents..]", "Lint JSON/YAML documents against a ruleset").positional("documents", { describe: "Documents or globs to lint", type: "string", array: true }).option("ruleset", { alias: "r", type: "string", describe: "Path to a ruleset file" }).option("encoding", { type: "string", default: "utf8", describe: "Input encoding" }).option("fail-severity", { alias: "F", type: "string", default: "error", choices: Object.keys(SEVERITY_BY_NAME) }).option("display-only-failures", { alias: "D", type: "boolean", default: false }).option("verbose", { type: "boolean", default: false }).option("quiet", { alias: "q", type: "boolean", default: false }).option("stdin-filepath", {
-    type: "string",
-    describe: "Path to associate with stdin input (labels findings and enables ruleset discovery)"
-  }).option("concurrency", {
-    type: "number",
-    default: 8,
-    describe: "Maximum number of documents to lint in parallel"
-  }).option("resolve", {
-    type: "boolean",
-    default: true,
-    describe: "Dereference $ref / $dynamicRef / $recursiveRef before linting (use --no-resolve to disable)"
-  }).option("resolve-remote", {
-    type: "boolean",
-    default: false,
-    describe: "Allow fetching http(s) $refs while resolving (off by default; a lint run stays offline)"
-  }).option("allowed-hosts", {
-    type: "string",
-    array: true,
-    describe: "Restrict remote $ref fetches to these hosts (implies --resolve-remote)"
-  }).option("allow-private-hosts", {
-    type: "boolean",
-    default: false,
-    describe: "Permit remote $refs to private/loopback hosts (SSRF guard, off by default)"
-  }).help().alias("help", "h").parse();
+  const outcome = await parseArgs(argv);
+  if ("error" in outcome) {
+    return { code: 2, stdout: "", stderr: `${outcome.error}
+Run \`mjst lint --help\` for the supported flags.
+` };
+  }
+  const parsed = outcome.args;
+  if (parsed.help)
+    return { code: 0, stdout: "", stderr: "" };
   const failSeverity = SEVERITY_BY_NAME[parsed.failSeverity] ?? DiagnosticSeverity.Error;
   const allowRemote = parsed.resolveRemote || (parsed.allowedHosts?.length ?? 0) > 0;
   const resolver = parsed.resolve ? createLintResolver({
     remote: allowRemote,
     ...parsed.allowedHosts ? { allowedHosts: parsed.allowedHosts } : {},
-    allowPrivateHosts: parsed.allowPrivateHosts
+    allowPrivateHosts: parsed.allowPrivateHosts,
+    ...parsed.allowedRoots ? { allowedRoots: parsed.allowedRoots } : {}
   }) : void 0;
   const reportRulesetProblems = (definition, label) => {
     if (parsed.quiet)
@@ -105,8 +131,13 @@ const run = async (argv, options = {}) => {
     rulesetBasePath = dirname(isAbsolute(parsed.ruleset) ? parsed.ruleset : resolve(process.cwd(), parsed.ruleset));
     reportRulesetProblems(rulesetDefinition, parsed.ruleset);
   }
-  const targets = await fg(parsed.documents ?? [], { dot: true, onlyFiles: true });
+  const documents = parsed.documents ?? [];
+  const targets = await fg(documents, { dot: true, onlyFiles: true });
   const allResults = [];
+  if (targets.length === 0 && documents.length > 0) {
+    return { code: 2, stdout: "", stderr: `No files matched: ${documents.join(", ")}
+` };
+  }
   if (targets.length === 0) {
     if (options.stdin === void 0 && process.stdin.isTTY) {
       return { code: 2, stdout: "", stderr: "No documents provided.\n" };

package/dist/load-config.d.ts

@@ -2,5 +2,9 @@ import type { CliConfig } from './cli-config.js';
 /**
  * Loads a JSON config file and returns the relevant CLI config properties.
  * The config file should have the same keys as the CLI flags (schema, outDir).
+ *
+ * Every key is validated up front (see {@link validateConfig}), so the `typeof`
+ * guards below are only here to narrow the types for TypeScript — by the time we
+ * reach them, nothing can fail them.
  */
 export declare const loadConfig: (configPath: string) => Promise<Partial<CliConfig>>;

package/dist/load-config.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { validateConfig } from "./validate-config.js";
 const SOURCE_FORMATS = ["json", "typebox", "zod", "valibot", "effect"];
 const isSourceFormat = (value) => typeof value === "string" && SOURCE_FORMATS.includes(value);
 const isHelpersMode = (value) => value === "package" || value === "embedded";
@@ -7,12 +8,17 @@ const isImportExt = (value) => value === "js" || value === "ts";
 const isStringArray = (value) => Array.isArray(value) && value.every((entry) => typeof entry === "string");
 const loadConfig = async (configPath) => {
   const absolutePath = resolve(configPath);
-  const raw = await readFile(absolutePath, "utf-8");
+  const raw = await readFile(absolutePath, "utf-8").catch((error) => {
+    if (error.code === "ENOENT")
+      throw new Error(`Config file not found: ${absolutePath}`);
+    throw error;
+  });
   const parsed = JSON.parse(raw);
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
     throw new Error(`Config file must be a JSON object: ${configPath}`);
   }
   const obj = parsed;
+  validateConfig(obj, configPath);
   return {
     ...typeof obj["schema"] === "string" && { schema: obj["schema"] },
     ...typeof obj["schemaDir"] === "string" && { schemaDir: obj["schemaDir"] },
@@ -24,6 +30,7 @@ const loadConfig = async (configPath) => {
     ...typeof obj["typesOnly"] === "boolean" && { typesOnly: obj["typesOnly"] },
     ...typeof obj["examples"] === "boolean" && { examples: obj["examples"] },
     ...typeof obj["build"] === "boolean" && { build: obj["build"] },
+    ...typeof obj["force"] === "boolean" && { force: obj["force"] },
     ...typeof obj["logWarnings"] === "boolean" && { logWarnings: obj["logWarnings"] },
     ...typeof obj["strict"] === "boolean" && { strict: obj["strict"] },
     ...typeof obj["stripUnknown"] === "boolean" && { stripUnknown: obj["stripUnknown"] },
@@ -37,7 +44,11 @@ const loadConfig = async (configPath) => {
     ...(typeof obj["banner"] === "boolean" || typeof obj["banner"] === "string") && { banner: obj["banner"] },
     ...typeof obj["resolveRemote"] === "boolean" && { resolveRemote: obj["resolveRemote"] },
     ...isStringArray(obj["allowedHosts"]) && { allowedHosts: obj["allowedHosts"] },
-    ...typeof obj["allowPrivateHosts"] === "boolean" && { allowPrivateHosts: obj["allowPrivateHosts"] }
+    ...typeof obj["allowPrivateHosts"] === "boolean" && { allowPrivateHosts: obj["allowPrivateHosts"] },
+    // Kept as written: like `schema` and `outDir`, a relative entry is resolved
+    // against the process working directory rather than the config file's
+    // directory, so one rule covers both flags and config keys.
+    ...isStringArray(obj["allowedRoots"]) && { allowedRoots: obj["allowedRoots"] }
   };
 };
 export {

package/dist/load-schema.js

@@ -1,18 +1,22 @@
 import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
 import { getAdapter } from "@amritk/adapters/get-adapter";
 import { resolveRefsFromFile } from "@amritk/resolve-refs";
+import { withAllowedRootsHint } from "./allowed-roots-hint.js";
 import { hasExternalRefs } from "./has-external-refs.js";
 import { loadSchemaModule } from "./load-schema-module.js";
-const buildResolveOptions = (config) => {
+const buildResolveOptions = (config, schemaPath) => {
   const remote = (config.resolveRemote ?? false) || (config.allowedHosts?.length ?? 0) > 0;
+  const extraRoots = (config.allowedRoots ?? []).map((root) => resolve(root));
   return {
     remote,
+    ...extraRoots.length > 0 ? { allowedRoots: [dirname(resolve(schemaPath)), ...extraRoots] } : {},
     ...config.allowedHosts ? { allowedHosts: [...config.allowedHosts] } : {},
     ...config.allowPrivateHosts ? { allowPrivateHosts: config.allowPrivateHosts } : {}
   };
 };
 const formatResolveErrors = (schemaPath, errors) => {
-  const details = errors.map((error) => `  - ${error.message}`).join("\n");
+  const details = errors.map((error) => `  - ${withAllowedRootsHint(error.message)}`).join("\n");
   return `Failed to resolve $refs in ${schemaPath}:
 ${details}`;
 };
@@ -22,7 +26,7 @@ const loadSchema = async (config, schemaPath) => {
     const data = JSON.parse(await readFile(schemaPath, "utf-8"));
     if (!hasExternalRefs(data))
       return data;
-    const { resolved, errors } = await resolveRefsFromFile(schemaPath, buildResolveOptions(config));
+    const { resolved, errors } = await resolveRefsFromFile(schemaPath, buildResolveOptions(config, schemaPath));
     if (errors.length > 0)
       throw new Error(formatResolveErrors(schemaPath, errors));
     return resolved;

package/dist/parse-cli-args.d.ts

@@ -1,4 +1,13 @@
 import type { CliConfig } from './cli-config.js';
+/**
+ * True when `--<flagName>` consumes the argument that follows it (`--banner`
+ * takes an optional one, which still swallows the next non-flag token).
+ *
+ * Exported because whoever inspects raw argv before parsing — the version/help
+ * detection in `cli.ts` — has to know that the `-v` in `--type-suffix -v` is a
+ * *value*, not a request to print the version.
+ */
+export declare const flagTakesValue: (flagName: string) => boolean;
 /**
  * Parses command-line arguments into a partial CLI config.
  * Every flag accepts both kebab-case and camelCase (e.g. `--out-dir` and `--outDir`)

package/dist/parse-cli-args.js

@@ -1,9 +1,11 @@
 const SOURCE_FORMATS = ["json", "typebox", "zod", "valibot", "effect"];
+const LIST_KEYS = /* @__PURE__ */ new Set(["allowedHosts", "allowedRoots"]);
 const BOOLEAN_KEYS = /* @__PURE__ */ new Set([
   "typesOnly",
   "validators",
   "examples",
   "build",
+  "force",
   "logWarnings",
   "strict",
   "stripUnknown",
@@ -26,6 +28,10 @@ const VALUE_KEYS = /* @__PURE__ */ new Set([
 ]);
 const EXTERNAL_VALUE_KEYS = /* @__PURE__ */ new Set(["config"]);
 const toCamelCase = (key) => key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+const flagTakesValue = (flagName) => {
+  const key = toCamelCase(flagName);
+  return VALUE_KEYS.has(key) || LIST_KEYS.has(key) || EXTERNAL_VALUE_KEYS.has(key) || key === "banner";
+};
 const parseHelpersValue = (value) => {
   if (value === "package" || value === "embedded")
     return value;
@@ -37,11 +43,11 @@ const parseImportExtValue = (value) => {
   return void 0;
 };
 const parseInputValue = (value) => SOURCE_FORMATS.includes(value) ? value : void 0;
-const appendAllowedHosts = (config, value) => {
-  const hosts = value.split(",").map((host) => host.trim()).filter((host) => host.length > 0);
-  if (hosts.length === 0)
+const appendListValue = (config, key, value) => {
+  const entries = value.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+  if (entries.length === 0)
     return;
-  config.allowedHosts = [...config.allowedHosts ?? [], ...hosts];
+  config[key] = [...config[key] ?? [], ...entries];
 };
 const assignValue = (config, key, value) => {
   switch (key) {
@@ -108,6 +114,9 @@ const assignBoolean = (config, key, value) => {
     case "build":
       config.build = value;
       return true;
+    case "force":
+      config.force = value;
+      return true;
     case "logWarnings":
       config.logWarnings = value;
       return true;
@@ -137,8 +146,12 @@ const parseCliArgs = (args) => {
   const config = {};
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
-    if (!arg || !arg.startsWith("--")) {
+    if (!arg)
       continue;
+    if (arg === "--")
+      break;
+    if (!arg.startsWith("--")) {
+      throw new Error(`Unexpected argument "${arg}". mjst takes flags only \u2014 did you mean a subcommand (\`mjst lint\`, \`mjst compile-api\`)?`);
     }
     const equalsIndex = arg.indexOf("=");
     if (equalsIndex !== -1) {
@@ -146,13 +159,16 @@ const parseCliArgs = (args) => {
       const value = arg.slice(equalsIndex + 1);
       if (key2 === "banner") {
         config.banner = value === "false" ? false : value === "true" ? true : value;
-      } else if (key2 === "allowedHosts") {
-        appendAllowedHosts(config, value);
+      } else if (LIST_KEYS.has(key2)) {
+        appendListValue(config, key2, value);
       } else if (BOOLEAN_KEYS.has(key2)) {
         assignBoolean(config, key2, value !== "false");
       } else if (VALUE_KEYS.has(key2)) {
         assignValue(config, key2, value);
-      } else if (!EXTERNAL_VALUE_KEYS.has(key2)) {
+      } else if (EXTERNAL_VALUE_KEYS.has(key2)) {
+        if (value === "")
+          throw new Error(`Flag "--${arg.slice(2, equalsIndex)}" expects a value.`);
+      } else {
         throw new Error(`Unknown flag "--${arg.slice(2, equalsIndex)}".`);
       }
       continue;
@@ -169,12 +185,12 @@ const parseCliArgs = (args) => {
       }
       continue;
     }
-    if (key === "allowedHosts") {
+    if (LIST_KEYS.has(key)) {
       const value = args[i + 1];
       if (value === void 0 || value.startsWith("--")) {
         throw new Error(`Flag "--${flagName}" expects a value.`);
       }
-      appendAllowedHosts(config, value);
+      appendListValue(config, key, value);
       i++;
       continue;
     }
@@ -193,8 +209,10 @@ const parseCliArgs = (args) => {
     }
     if (EXTERNAL_VALUE_KEYS.has(key)) {
       const value = args[i + 1];
-      if (value !== void 0 && !value.startsWith("--"))
-        i++;
+      if (value === void 0 || value.startsWith("--")) {
+        throw new Error(`Flag "--${flagName}" expects a value.`);
+      }
+      i++;
       continue;
     }
     throw new Error(`Unknown flag "--${flagName}".`);
@@ -202,5 +220,6 @@ const parseCliArgs = (args) => {
   return config;
 };
 export {
+  flagTakesValue,
   parseCliArgs
 };

package/dist/parse-meta-request.d.ts

@@ -0,0 +1,15 @@
+/** A request that short-circuits generation and just prints something. */
+export type MetaRequest = 'version' | 'help';
+/**
+ * Detects `mjst version` / `mjst help` and the `--version` / `-v` / `--help` /
+ * `-h` flags in raw argv.
+ *
+ * The subtlety is *where* the token sits. Scanning the whole argv with
+ * `includes('-v')` meant that any flag whose **value** happened to be `-v` — say
+ * `--type-suffix -v` — printed the version and exited 0 without generating
+ * anything, which CI reads as a successful build. So a token in the value
+ * position of a value-taking flag is skipped: it belongs to that flag.
+ *
+ * @returns What the args ask for, or `undefined` for a normal generation run.
+ */
+export declare const parseMetaRequest: (args: readonly string[]) => MetaRequest | undefined;

package/dist/parse-meta-request.js

@@ -0,0 +1,22 @@
+import { flagTakesValue } from "./parse-cli-args.js";
+const parseMetaRequest = (args) => {
+  if (args[0] === "version")
+    return "version";
+  if (args[0] === "help")
+    return "help";
+  for (let i = 0; i < args.length; i++) {
+    const previous = i > 0 ? args[i - 1] : void 0;
+    const consumedAsValue = previous?.startsWith("--") && !previous.includes("=") && flagTakesValue(previous.slice(2));
+    if (consumedAsValue)
+      continue;
+    const arg = args[i];
+    if (arg === "--version" || arg === "-v")
+      return "version";
+    if (arg === "--help" || arg === "-h")
+      return "help";
+  }
+  return void 0;
+};
+export {
+  parseMetaRequest
+};

package/dist/validate-config.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The JSON type each config key accepts, mirroring `config.schema.json`.
+ * `boolean|string` is `banner`'s `"type": ["boolean", "string"]`.
+ */
+type ConfigValueType = 'string' | 'boolean' | 'boolean|string' | 'string[]';
+/** One key's contract: its JSON type, plus the closed value set when it has one. */
+type ConfigKeySpec = {
+    readonly type: ConfigValueType;
+    readonly enum?: readonly string[];
+};
+/**
+ * Every key a config file may carry, kept in lockstep with `config.schema.json`
+ * by `validate-config.test.ts`.
+ *
+ * The schema itself would be the obvious thing to validate against at runtime,
+ * but it is deliberately not shipped in the published package (see `help-text.ts`
+ * for the same trade-off), and `@amritk/runtime-validators` — the interpreter that
+ * would run it — is not a declared dependency of this package. So the contract
+ * lives here as data, and the test pins it to the schema so the two cannot drift.
+ * (Exported for exactly that test — nothing else should read it.)
+ */
+export declare const CONFIG_KEYS: Record<string, ConfigKeySpec>;
+/**
+ * Checks a parsed config file against the key contract, throwing with every
+ * problem found (JSON Pointer + what was expected).
+ *
+ * Before this, each key was guarded by a `typeof` check whose failure branch was
+ * "drop it": `{"strcit": true, "strict": "true"}` generated non-strict output and
+ * exited 0, while the very same typo on the command line was rejected. A config
+ * file has to be at least as strict as the flags it stands in for.
+ *
+ * Note what this does *not* buy: a config is still trusted code. `schema` plus a
+ * non-`json` `input` makes `load-schema-module.ts` `import()` whatever path the
+ * config names, so an untrusted `mjst.config.json` still reaches arbitrary module
+ * evaluation. Validating the shape does not change that — do not run mjst against
+ * a config file you would not run as a script.
+ */
+export declare const validateConfig: (parsed: Record<string, unknown>, configPath: string) => void;
+export {};

package/dist/validate-config.js

@@ -0,0 +1,75 @@
+const CONFIG_KEYS = {
+  schema: { type: "string" },
+  schemaDir: { type: "string" },
+  input: { type: "string", enum: ["json", "typebox", "zod", "valibot", "effect"] },
+  export: { type: "string" },
+  outDir: { type: "string" },
+  outFile: { type: "string" },
+  typesOnly: { type: "boolean" },
+  validators: { type: "boolean" },
+  examples: { type: "boolean" },
+  build: { type: "boolean" },
+  force: { type: "boolean" },
+  logWarnings: { type: "boolean" },
+  strict: { type: "boolean" },
+  stripUnknown: { type: "boolean" },
+  caseInsensitive: { type: "boolean" },
+  readonly: { type: "boolean" },
+  helpers: { type: "string", enum: ["package", "embedded"] },
+  typeSuffix: { type: "string" },
+  banner: { type: "boolean|string" },
+  importExt: { type: "string", enum: ["js", "ts"] },
+  rootType: { type: "string" },
+  resolveRemote: { type: "boolean" },
+  allowedHosts: { type: "string[]" },
+  allowPrivateHosts: { type: "boolean" },
+  allowedRoots: { type: "string[]" },
+  config: { type: "string" }
+};
+const typeNameOf = (value) => {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "array";
+  return typeof value;
+};
+const matchesType = (value, type) => {
+  switch (type) {
+    case "string":
+      return typeof value === "string";
+    case "boolean":
+      return typeof value === "boolean";
+    case "boolean|string":
+      return typeof value === "boolean" || typeof value === "string";
+    case "string[]":
+      return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+  }
+};
+const validateConfig = (parsed, configPath) => {
+  const problems = [];
+  const knownKeys = Object.keys(CONFIG_KEYS);
+  for (const [key, value] of Object.entries(parsed)) {
+    const spec = CONFIG_KEYS[key];
+    if (!spec) {
+      if (key === "$schema")
+        continue;
+      problems.push(`  /${key}: unknown option. Known options: ${knownKeys.join(", ")}.`);
+      continue;
+    }
+    if (!matchesType(value, spec.type)) {
+      problems.push(`  /${key}: expected ${spec.type}, received ${typeNameOf(value)}.`);
+      continue;
+    }
+    if (spec.enum && typeof value === "string" && !spec.enum.includes(value)) {
+      problems.push(`  /${key}: expected one of ${spec.enum.join(", ")}, received "${value}".`);
+    }
+  }
+  if (problems.length > 0) {
+    throw new Error(`Invalid config file ${configPath}:
+${problems.join("\n")}`);
+  }
+};
+export {
+  CONFIG_KEYS,
+  validateConfig
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.13.9",
+  "version": "0.14.8",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "engines": {
@@ -39,27 +39,31 @@
   "scripts": {
     "dev": "bun run --conditions=development ./src/cli.ts",
     "start": "bun run ./src/cli.ts",
-    "build": "tsgo -p tsconfig.build.json && tsc-alias -p tsconfig.build.json -f && node ../../scripts/strip-comments.mjs",
+    "build": "tsgo -p tsconfig.build.json && tsc-alias -p tsconfig.build.json -f && node ../../scripts/strip-comments.mjs && node ../../scripts/chmod-bin.mjs",
+    "prepublishOnly": "node ../../scripts/check-publishable.mjs",
     "types:check": "tsgo -p . --noEmit",
     "test": "NODE_ENV=production vitest run --root ../.. cli",
     "generate-readme": "bun run ./scripts/generate-readme.ts"
   },
+  "exports": {
+    "./package.json": "./package.json"
+  },
   "dependencies": {
-    "@amritk/adapters": "0.3.6",
-    "@amritk/api": "0.12.0",
-    "@amritk/generate-examples": "0.5.6",
-    "@amritk/generate-parsers": "0.18.0",
-    "@amritk/generate-validators": "0.11.12",
-    "@amritk/generate-markdown": "0.4.5",
-    "@amritk/helpers": "0.14.0",
-    "@amritk/lint": "0.4.3",
-    "@amritk/resolve-refs": "0.4.5",
-    "@amritk/yaml": "0.4.0",
+    "@amritk/adapters": "^0.4.3",
+    "@amritk/api": "^0.15.1",
+    "@amritk/generate-examples": "^0.6.3",
+    "@amritk/generate-parsers": "^0.19.3",
+    "@amritk/generate-validators": "^0.13.0",
+    "@amritk/helpers": "^0.15.3",
+    "@amritk/lint": "^0.4.7",
+    "@amritk/resolve-refs": "^0.6.0",
+    "@amritk/yaml": "^0.7.1",
     "fast-glob": "^3.3.2",
+    "json-schema-typed": "^8.0.1",
     "yargs": "^17.7.2"
   },
   "devDependencies": {
-    "json-schema-typed": "^8.0.1",
+    "@amritk/generate-markdown": "^0.4.8",
     "@types/yargs": "^17.0.33"
   }
 }