@amritk/mjst 0.13.9 → 0.14.8

package/README.md

@@ -144,11 +144,16 @@ npx mjst --schema ./order.json --out-dir ./generated
 
 Same-document refs (`#/$defs/...`) are left untouched — the generator resolves those
 itself into named type files, so nothing changes for schemas that only reference
-themselves. Local cross-file refs resolve from disk with no extra flags. Remote
-(`http(s)`) refs stay **offline by default**: a schema with a remote `$ref` fails
-rather than making a network call unless you opt in.
+themselves. Local cross-file refs resolve from disk with no extra flags, as long as
+they stay **inside the schema's own directory** — a `$ref` cannot walk out of the tree
+it belongs to (`../../../secrets.env`, or an absolute path) unless you name the extra
+directory with `--allowed-roots`. Remote (`http(s)`) refs stay **offline by default**:
+a schema with a remote `$ref` fails rather than making a network call unless you opt in.
 
 ```bash
+# Let a split spec reach a sibling folder: v1/api.json → ../common/user.json
+npx mjst --schema ./specs/v1/api.json --out-dir ./generated --allowed-roots ./specs
+
 # Allow remote $ref fetches
 npx mjst --schema ./order.json --out-dir ./generated --resolve-remote
 
@@ -159,6 +164,11 @@ npx mjst --schema ./order.json --out-dir ./generated --allowed-hosts schemas.exa
 npx mjst --schema ./order.json --out-dir ./generated --resolve-remote --allow-private-hosts
 ```
 
+`--allowed-roots` takes a comma-separated list (or repeat the flag) and resolves each
+entry against the current working directory. It **adds** to the schema's own directory
+rather than replacing it, and everything outside the resulting set is still refused —
+so widening the roots for a shared `common/` folder does not reopen the whole disk.
+
 Unresolvable references (a missing file, a refused host, a bad URL) fail the run with
 the underlying reason rather than emitting a half-resolved schema. This works with
 `--schema-dir` too — each schema resolves its own external references.
@@ -211,9 +221,10 @@ With no `-r`, mjst discovers a `.lint.{yaml,yml,json,js,mjs}` ruleset by walking
 | `--resolve-remote` | Fetch `http(s)` `$ref`s while resolving (off by default; a lint run stays offline). |
 | `--allowed-hosts` | Restrict remote `$ref` fetches to these hosts (implies `--resolve-remote`). |
 | `--allow-private-hosts` | Permit remote `$ref`s to private/loopback hosts (SSRF guard, off by default). |
+| `--allowed-roots` | Extra directories a local `$ref` may resolve into, on top of the document's own (repeat the flag). |
 | `-q`, `--quiet` | Suppress the findings report (the exit code still reflects findings). |
 
-By default `mjst lint` dereferences `$ref`, `$dynamicRef`/`$dynamicAnchor`, and `$recursiveRef`/`$recursiveAnchor` before running rules, so rules with `resolved: true` (the ruleset default) see through references. Internal and local cross-file refs resolve from disk — a finding on a cross-file node reports that file's own `line:column` — while remote refs are only fetched when you opt in with `--resolve-remote` or `--allowed-hosts`.
+By default `mjst lint` dereferences `$ref`, `$dynamicRef`/`$dynamicAnchor`, and `$recursiveRef`/`$recursiveAnchor` before running rules, so rules with `resolved: true` (the ruleset default) see through references. Internal and local cross-file refs resolve from disk — a finding on a cross-file node reports that file's own `line:column` — as long as they stay inside the linted document's own directory; use `--allowed-roots` to let a document reach a shared sibling folder. Remote refs are only fetched when you opt in with `--resolve-remote` or `--allowed-hosts`.
 
 The exit code is `0` when no finding reaches `--fail-severity`, `1` when one does, and `2` on a usage error. Run `mjst lint --help` for the full list.
 
@@ -350,6 +361,15 @@ The exit code is `0` on success, `1` when compilation fails (unloadable module,
 <td colspan="4">Compile the generated TypeScript files to .js and .d.ts output. A temporary tsconfig is written to the output directory, tsc is invoked, and the intermediate .ts source files are removed when compilation succeeds.</td>
 </tr>
 <tr>
+<td>💥 <code>force</code></td>
+<td><code>--force</code></td>
+<td><code>boolean</code></td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="4">Allow generated files to overwrite files that already exist in the output destination. By default a collision with a file mjst did not generate (a hand-written index.ts, say) aborts the run before anything is written, because the generator would otherwise replace it — and, under build, delete it along with the other intermediate sources. Regenerating never needs this flag: each run records what it wrote in a .mjst-manifest.json at the root of the output directory, and anything listed there is replaced freely.</td>
+</tr>
+<tr>
 <td>⚠️ <code>logWarnings</code></td>
 <td><code>--log-warnings</code></td>
 <td><code>boolean</code></td>
@@ -467,13 +487,22 @@ The exit code is `0` on success, `1` when compilation fails (unloadable module,
 <td colspan="4">Permit remote $refs to private, loopback, and link-local hosts. Off by default: such targets are refused as a best-effort SSRF guard (notably the 169.254.169.254 cloud-metadata endpoint). An explicit allowedHosts entry always bypasses this guard.</td>
 </tr>
 <tr>
+<td>📂 <code>allowedRoots</code></td>
+<td><code>--allowed-roots &lt;dirs&gt;</code></td>
+<td><code>array</code></td>
+<td align="center"></td>
+</tr>
+<tr>
+<td colspan="4">Extra directories a local (cross-file) $ref may resolve into. By default a local $ref is confined to the schema's own directory, so '{"$ref": "../../../secrets.env"}' (or an absolute path) reads nothing. List a root here for the ordinary split-spec layout where v1/api.json refers to a shared common/user.json one level up. The schema's own directory is always allowed, so these roots widen the default rather than replacing it, and a $ref that still lands outside every root is refused. Accepts a comma-separated list or the flag repeated; relative entries resolve against the current working directory, from a config file as well as from the flag.<br><strong>Examples:</strong> <code>["./specs"]</code></td>
+</tr>
+<tr>
 <td>⚙️ <code>config</code></td>
 <td><code>--config &lt;path&gt;</code></td>
 <td><code>string</code></td>
 <td align="center"></td>
 </tr>
 <tr>
-<td colspan="4">Path to a JSON config file. Keys match the option names in this schema (schema, schemaDir, input, export, outDir, outFile, typesOnly, validators, examples, build, logWarnings, strict, stripUnknown, caseInsensitive, readonly, helpers, typeSuffix, banner, importExt, rootType, resolveRemote, allowedHosts, allowPrivateHosts). CLI flags take precedence over config file values.<br><strong>Examples:</strong> <code>"./mjst.config.json"</code></td>
+<td colspan="4">Path to a JSON config file. Keys match the option names in this schema (schema, schemaDir, input, export, outDir, outFile, typesOnly, validators, examples, build, force, logWarnings, strict, stripUnknown, caseInsensitive, readonly, helpers, typeSuffix, banner, importExt, rootType, resolveRemote, allowedHosts, allowPrivateHosts, allowedRoots) and are validated: an unknown key or a wrong value type fails the run instead of being ignored. CLI flags take precedence over config file values.<br><strong>Examples:</strong> <code>"./mjst.config.json"</code></td>
 </tr>
 </tbody>
 </table>

package/dist/allowed-roots-hint.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Appends {@link ALLOWED_ROOTS_HINT} to a resolver message that blames
+ * `allowedRoots`, and leaves every other message untouched. Matching on the
+ * option name rather than the full sentence keeps this working across both
+ * refusal wordings the resolver produces ("resolves outside the allowed roots"
+ * and "no local directory is allowed for this document").
+ */
+export declare const withAllowedRootsHint: (message: string) => string;

package/dist/allowed-roots-hint.js

@@ -0,0 +1,5 @@
+const ALLOWED_ROOTS_HINT = "\u2014 pass --allowed-roots <dir> to permit it (relative paths resolve against the current directory).";
+const withAllowedRootsHint = (message) => message.includes("allowedRoots") ? `${message} ${ALLOWED_ROOTS_HINT}` : message;
+export {
+  withAllowedRootsHint
+};

package/dist/cli-config.d.ts

@@ -60,6 +60,18 @@ export type CliConfig = {
      * The .ts source files are removed after compilation.
      */
     readonly build?: boolean;
+    /**
+     * When true, generated files may overwrite files that already exist in the
+     * output destination. By default a collision with a file mjst did not generate
+     * (a hand-written `index.ts`, say) aborts the run rather than silently
+     * replacing it — and with `build`, deleting it afterwards. Regeneration does
+     * not need this: each run records what it wrote in a `.mjst-manifest.json` at
+     * the root of the output directory, and reclaims those paths freely. With
+     * `outFile` the "output directory" is the directory holding that file, so the
+     * manifest lands beside it — generated examples and the `build` output already
+     * do.
+     */
+    readonly force?: boolean;
     /**
      * When true, the generated parsers emit a console.warn for every input key
      * that is not declared in the schema's properties.
@@ -160,4 +172,17 @@ export type CliConfig = {
      * always bypasses this guard.
      */
     readonly allowPrivateHosts?: boolean;
+    /**
+     * Extra directories a local (cross-file) `$ref` may resolve into. A local
+     * `$ref` is confined to the schema's own directory by default, so a
+     * `{"$ref": "../../../secrets.env"}` reads nothing; this is the escape hatch for
+     * the ordinary split-spec layout where `v1/api.json` refers to a shared
+     * `common/user.json` one level up.
+     *
+     * The schema's own directory is always allowed, so the listed roots widen the
+     * default rather than replacing it. Entries are resolved against the process
+     * working directory — including entries that came from a config file, which
+     * matches how `schema` and `outDir` are treated.
+     */
+    readonly allowedRoots?: readonly string[];
 };

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { execFile } from "node:child_process";
-import { mkdir, readdir, unlink, writeFile } from "node:fs/promises";
+import { readdir, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { buildSchema } from "@amritk/generate-parsers";
@@ -8,16 +8,18 @@ import { buildValidatorSchema } from "@amritk/generate-validators";
 import { deriveRootTypeName } from "@amritk/helpers/derive-root-type-name";
 const execFileAsync = promisify(execFile);
 import { combineGeneratedFiles } from "./combine-files.js";
+import { createOutputWriter } from "./create-output-writer.js";
 import { detectHelpersMode } from "./detect-helpers-mode.js";
 import { emitExamples } from "./emit-examples.js";
+import { ensureOutputDir } from "./ensure-output-dir.js";
 import { HELP_TEXT } from "./help-text.js";
 import { loadConfig } from "./load-config.js";
 import { loadSchema } from "./load-schema.js";
 import { parseCliArgs } from "./parse-cli-args.js";
+import { parseMetaRequest } from "./parse-meta-request.js";
 import { readVersion } from "./read-version.js";
 import { resolveImportExt } from "./resolve-import-ext.js";
-const isVersionRequest = (args) => args[0] === "version" || args.includes("--version") || args.includes("-v");
-const isHelpRequest = (args) => args[0] === "help" || args.includes("--help") || args.includes("-h");
+const ROOT_TYPE_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 const schemaBaseName = (schemaPath) => basename(schemaPath).replace(/\.[^.]+$/, "");
 const resolveHelpersMode = (config, outputDir) => {
   const helpersMode = config.helpers ?? detectHelpersMode(outputDir);
@@ -50,21 +52,30 @@ const resolveBanner = (banner) => {
 
 `;
 };
-const writeGeneratedFile = async (baseDir, filename, content) => {
-  const filePath = join(baseDir, filename);
-  await mkdir(dirname(filePath), { recursive: true });
-  await writeFile(filePath, content, "utf-8");
+const commitOrDiscard = async (writer, stageAll) => {
+  try {
+    await stageAll();
+  } catch (error) {
+    await writer.discard();
+    throw error;
+  }
+  return writer.commit();
 };
-const runExamples = async (config, schema, rootTypeName, outputDir, subDir = "") => {
-  const written = await emitExamples({
-    schema,
-    rootTypeName,
-    outputDir,
-    subDir,
-    bannerPrefix: config.banner ? resolveBanner(config.banner) : "",
-    // Spread conditionally: `exactOptionalPropertyTypes` rejects an explicit
-    // `undefined` for the optional `typeSuffix`.
-    ...config.typeSuffix !== void 0 ? { typeSuffix: config.typeSuffix } : {}
+const runExamples = async (config, outputDir, tasks) => {
+  const writer = await createOutputWriter(outputDir, config.force);
+  const written = await commitOrDiscard(writer, async () => {
+    for (const task of tasks) {
+      await emitExamples({
+        schema: task.schema,
+        rootTypeName: task.rootTypeName,
+        writer,
+        subDir: task.subDir ?? "",
+        bannerPrefix: config.banner ? resolveBanner(config.banner) : "",
+        // Spread conditionally: `exactOptionalPropertyTypes` rejects an explicit
+        // `undefined` for the optional `typeSuffix`.
+        ...config.typeSuffix !== void 0 ? { typeSuffix: config.typeSuffix } : {}
+      });
+    }
   });
   for (const path of written) {
     console.log(`Generated example: ${path}`);
@@ -100,11 +111,12 @@ ${output}` : ""}`);
   }
   for (const file of tsFiles) {
     await unlink(join(outputDir, file));
-    console.log(`Built: ${file.replace(/\.ts$/, ".js")}`);
+    if (!typesOnly)
+      console.log(`Built: ${file.replace(/\.ts$/, ".js")}`);
     console.log(`Built: ${file.replace(/\.ts$/, ".d.ts")}`);
   }
   console.log(`
-Total files built: ${tsFiles.length * 2}`);
+Total files built: ${tsFiles.length * (typesOnly ? 1 : 2)}`);
 };
 const findJsonSchemas = async (dir) => {
   const entries = await readdir(dir, { withFileTypes: true });
@@ -121,60 +133,67 @@ const findJsonSchemas = async (dir) => {
   }
   return results;
 };
-const runValidators = async (config, schema, rootTypeName, outputDir, validatorsSubDir) => {
+const runValidators = async (config, schema, rootTypeName, writer, validatorsSubDir) => {
   const files = await buildValidatorSchema(schema, rootTypeName, config.typeSuffix);
-  const written = [];
+  const staged = [];
   for (const file of files) {
     const content = config.banner ? resolveBanner(config.banner) + file.content : file.content;
     const relFilename = join(validatorsSubDir, file.filename);
-    await writeGeneratedFile(outputDir, relFilename, content);
-    written.push(relFilename);
-    console.log(`Generated: ${relFilename}`);
+    await writer.stage(relFilename, content);
+    staged.push(relFilename);
   }
-  return written;
+  return staged;
 };
 const runSingle = async (config, schemaPath, outputDir) => {
   const schema = await loadSchema(config, schemaPath);
-  await mkdir(outputDir, { recursive: true });
+  await ensureOutputDir(outputDir);
   const helpersMode = resolveHelpersMode(config, outputDir);
   const rootTypeName = config.rootType ?? deriveRootTypeName(schema, schemaBaseName(schemaPath));
   console.log(`Root type: ${rootTypeName}`);
   const files = await buildSchema(schema, rootTypeName, void 0, config.typesOnly, config.logWarnings, config.strict, helpersMode, void 0, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config), config.caseInsensitive);
-  for (const file of files) {
-    const isHelper = file.filename.startsWith("_helpers/");
-    const content = config.banner && !isHelper ? resolveBanner(config.banner) + file.content : file.content;
-    await writeGeneratedFile(outputDir, file.filename, content);
-    console.log(`Generated: ${file.filename}`);
-  }
-  const validatorFiles = config.validators ? await runValidators(config, schema, rootTypeName, outputDir, "validators") : [];
+  const writer = await createOutputWriter(outputDir, config.force);
+  const written = await commitOrDiscard(writer, async () => {
+    for (const file of files) {
+      const isHelper = file.filename.startsWith("_helpers/");
+      const content = config.banner && !isHelper ? resolveBanner(config.banner) + file.content : file.content;
+      await writer.stage(file.filename, content);
+    }
+    if (config.validators)
+      await runValidators(config, schema, rootTypeName, writer, "validators");
+  });
+  for (const filename of written)
+    console.log(`Generated: ${filename}`);
   if (config.examples) {
-    await runExamples(config, schema, rootTypeName, outputDir);
+    await runExamples(config, outputDir, [{ schema, rootTypeName }]);
   }
   if (config.build) {
-    await buildOutput(outputDir, [...files.map((f) => f.filename), ...validatorFiles], config.typesOnly);
+    await buildOutput(outputDir, written, config.typesOnly);
   } else {
     console.log(`
-Total files generated: ${files.length + validatorFiles.length}`);
+Total files generated: ${written.length}`);
   }
 };
 const runSingleFile = async (config, schemaPath, outFilePath) => {
   const schema = await loadSchema(config, schemaPath);
   const outputDir = dirname(outFilePath);
-  await mkdir(outputDir, { recursive: true });
+  await ensureOutputDir(outputDir);
   const rootTypeName = config.rootType ?? deriveRootTypeName(schema, schemaBaseName(schemaPath));
   console.log(`Root type: ${rootTypeName}`);
   const files = await buildSchema(schema, rootTypeName, void 0, config.typesOnly, config.logWarnings, config.strict, config.helpers ?? "package", void 0, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config), config.caseInsensitive);
   const combined = combineGeneratedFiles(files);
-  await writeFile(outFilePath, config.banner ? resolveBanner(config.banner) + combined : combined, "utf-8");
+  const writer = await createOutputWriter(outputDir, config.force);
+  const written = await commitOrDiscard(writer, async () => {
+    await writer.stage(basename(outFilePath), config.banner ? resolveBanner(config.banner) + combined : combined);
+  });
   console.log(`Generated: ${relative(process.cwd(), outFilePath)}`);
   if (config.examples) {
-    await runExamples(config, schema, rootTypeName, outputDir);
+    await runExamples(config, outputDir, [{ schema, rootTypeName }]);
   }
   if (config.build) {
-    await buildOutput(outputDir, [basename(outFilePath)], config.typesOnly);
+    await buildOutput(outputDir, written, config.typesOnly);
   } else {
     console.log(`
-Total files generated: 1`);
+Total files generated: ${written.length}`);
   }
 };
 const runRecursive = async (config, schemaDir, outputDir) => {
@@ -187,44 +206,45 @@ const runRecursive = async (config, schemaDir, outputDir) => {
     console.error(`Error: no .json schema files found under ${schemaDir}.`);
     process.exit(1);
   }
-  await mkdir(outputDir, { recursive: true });
+  await ensureOutputDir(outputDir);
   const helpersMode = resolveHelpersMode(config, outputDir);
   const sharedHelpers = /* @__PURE__ */ new Map();
-  const writtenTsFiles = [];
-  for (const schemaFile of schemaFiles) {
-    const relPath = relative(schemaDir, schemaFile);
-    const relNoExt = relPath.slice(0, -".json".length);
-    const schemaSubDir = join(outputDir, relNoExt);
-    const depth = relNoExt.split(sep).filter(Boolean).length;
-    const helpersImportPrefix = "../".repeat(depth);
-    const schema = await loadSchema(config, schemaFile);
-    const rootTypeName = deriveRootTypeName(schema, schemaBaseName(schemaFile));
-    console.log(`
+  const writer = await createOutputWriter(outputDir, config.force);
+  const exampleTasks = [];
+  const stageAll = async () => {
+    for (const schemaFile of schemaFiles) {
+      const relPath = relative(schemaDir, schemaFile);
+      const relNoExt = relPath.slice(0, -".json".length);
+      const depth = relNoExt.split(sep).filter(Boolean).length;
+      const helpersImportPrefix = "../".repeat(depth);
+      const schema = await loadSchema(config, schemaFile);
+      const rootTypeName = deriveRootTypeName(schema, schemaBaseName(schemaFile));
+      console.log(`
 ${relPath} \u2192 ${relNoExt}/ (root type: ${rootTypeName})`);
-    const files = await buildSchema(schema, rootTypeName, void 0, config.typesOnly, config.logWarnings, config.strict, helpersMode, helpersImportPrefix, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config), config.caseInsensitive);
-    for (const file of files) {
-      if (file.filename.startsWith("_helpers/")) {
-        sharedHelpers.set(file.filename, file.content);
-        continue;
+      const files = await buildSchema(schema, rootTypeName, void 0, config.typesOnly, config.logWarnings, config.strict, helpersMode, helpersImportPrefix, config.readonly, config.stripUnknown, config.typeSuffix, resolveImportExt(config), config.caseInsensitive);
+      for (const file of files) {
+        if (file.filename.startsWith("_helpers/")) {
+          sharedHelpers.set(file.filename, file.content);
+          continue;
+        }
+        const content = config.banner ? resolveBanner(config.banner) + file.content : file.content;
+        await writer.stage(join(relNoExt, file.filename), content);
       }
-      const content = config.banner ? resolveBanner(config.banner) + file.content : file.content;
-      await writeGeneratedFile(schemaSubDir, file.filename, content);
-      const relativeFilename = join(relNoExt, file.filename);
-      writtenTsFiles.push(relativeFilename);
-      console.log(`Generated: ${relativeFilename}`);
-    }
-    if (config.validators) {
-      const validatorFiles = await runValidators(config, schema, rootTypeName, outputDir, join("validators", relNoExt));
-      writtenTsFiles.push(...validatorFiles);
+      if (config.validators) {
+        await runValidators(config, schema, rootTypeName, writer, join("validators", relNoExt));
+      }
+      if (config.examples)
+        exampleTasks.push({ schema, rootTypeName, subDir: relNoExt });
     }
-    if (config.examples) {
-      await runExamples(config, schema, rootTypeName, outputDir, relNoExt);
+    for (const [filename, content] of sharedHelpers) {
+      await writer.stage(filename, content);
     }
-  }
-  for (const [filename, content] of sharedHelpers) {
-    await writeGeneratedFile(outputDir, filename, content);
-    writtenTsFiles.push(filename);
+  };
+  const writtenTsFiles = await commitOrDiscard(writer, stageAll);
+  for (const filename of writtenTsFiles)
     console.log(`Generated: ${filename}`);
+  if (exampleTasks.length > 0) {
+    await runExamples(config, outputDir, exampleTasks);
   }
   if (config.build) {
     await buildOutput(outputDir, writtenTsFiles, config.typesOnly);
@@ -253,11 +273,12 @@ const run = async () => {
       process.stderr.write(result.stderr);
     process.exit(result.code);
   }
-  if (isVersionRequest(args)) {
+  const metaRequest = parseMetaRequest(args);
+  if (metaRequest === "version") {
     console.log(await readVersion());
     return;
   }
-  if (args.length === 0 || isHelpRequest(args)) {
+  if (args.length === 0 || metaRequest === "help") {
     console.log(HELP_TEXT);
     return;
   }
@@ -269,6 +290,10 @@ const run = async () => {
     console.error("Error: provide only one of --out-dir or --out-file, not both.");
     process.exit(1);
   }
+  if (config.rootType !== void 0 && !ROOT_TYPE_PATTERN.test(config.rootType)) {
+    console.error(`Error: invalid --root-type "${config.rootType}". Expected a TypeScript identifier (letters, digits, _ or $, not starting with a digit).`);
+    process.exit(1);
+  }
   if (config.rootType && config.schemaDir) {
     console.error("Error: --root-type cannot be combined with --schema-dir; each schema derives its own root type.");
     process.exit(1);

package/dist/create-output-writer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A two-phase writer for one generation run: every file is staged next to its
+ * final location under a temporary name, and only once the whole set is on disk
+ * are the temporaries renamed into place.
+ *
+ * Two failure modes drive the design:
+ *
+ * 1. **Partial trees.** Writing straight to the final paths meant a failure
+ *    halfway through (a `_helpers` path occupied by a regular file, a full disk)
+ *    left some generated files behind and others missing — a tree that compiles
+ *    against a schema that no longer exists. Staging first means the run either
+ *    lands completely or leaves the destination as it found it. Renaming is not
+ *    one atomic operation across the whole set, but every rename happens after
+ *    all the risky work (generating, creating directories, writing bytes) has
+ *    already succeeded, so it is the cheapest place to get the guarantee.
+ * 2. **Clobbering hand-written files.** A generated name can collide with a file
+ *    the user wrote (`index.ts` is the common one), which used to be overwritten
+ *    without a word — and then, under `--build`, deleted along with the other
+ *    intermediate sources. A file is only replaced when a previous run claimed it
+ *    (see {@link MANIFEST_FILENAME}) or `--force` says so, and `--build` is only
+ *    ever handed the paths this run actually committed.
+ */
+export type OutputWriter = {
+    /**
+     * Stages one file. `relativePath` is relative to the writer's root and may
+     * contain subdirectories; parent directories are created eagerly.
+     */
+    readonly stage: (relativePath: string, content: string) => Promise<void>;
+    /** Moves every staged file to its final path and returns the committed paths. */
+    readonly commit: () => Promise<string[]>;
+    /** Deletes the staged temporaries; call this when the run fails before committing. */
+    readonly discard: () => Promise<void>;
+};
+/**
+ * Creates an {@link OutputWriter} rooted at `rootDir`.
+ *
+ * @param rootDir - Output root. Every write must resolve inside it.
+ * @param force - Overwrite pre-existing files instead of refusing (`--force`).
+ */
+export declare const createOutputWriter: (rootDir: string, force?: boolean) => Promise<OutputWriter>;

package/dist/create-output-writer.js

@@ -0,0 +1,57 @@
+import { readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { ensureOutputDir } from "./ensure-output-dir.js";
+const MANIFEST_FILENAME = ".mjst-manifest.json";
+const pathExists = async (path) => stat(path).then(() => true, () => false);
+const readManifest = async (root) => {
+  const raw = await readFile(join(root, MANIFEST_FILENAME), "utf-8").catch(() => void 0);
+  if (raw === void 0)
+    return /* @__PURE__ */ new Set();
+  try {
+    const parsed = JSON.parse(raw);
+    const files = Array.isArray(parsed.files) ? parsed.files : [];
+    return new Set(files.filter((file) => typeof file === "string").map((file) => resolve(root, file)));
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+};
+const createOutputWriter = async (rootDir, force = false) => {
+  const root = resolve(rootDir);
+  const owned = await readManifest(root);
+  const staged = [];
+  const stamp = `${process.pid}-${Date.now().toString(36)}`;
+  const stage = async (relativePath, content) => {
+    const targetPath = resolve(root, relativePath);
+    if (targetPath !== root && !targetPath.startsWith(root + sep)) {
+      throw new Error(`Refusing to write "${relativePath}": it resolves outside the output directory ${root}.`);
+    }
+    if (!force && !owned.has(targetPath) && await pathExists(targetPath)) {
+      throw new Error(`Refusing to overwrite ${targetPath}: it already exists and was not generated by mjst. Move it aside, choose another output directory, or pass --force to overwrite it.`);
+    }
+    const tempPath = `${targetPath}.mjst-${stamp}-${staged.length}.tmp`;
+    await ensureOutputDir(dirname(targetPath));
+    await writeFile(tempPath, content, "utf-8");
+    staged.push({ relativePath, targetPath, tempPath });
+  };
+  const commit = async () => {
+    for (const file of staged) {
+      await rename(file.tempPath, file.targetPath);
+      owned.add(file.targetPath);
+    }
+    if (staged.length > 0) {
+      const files = [...owned].map((path) => relative(root, path)).sort();
+      await writeFile(join(root, MANIFEST_FILENAME), `${JSON.stringify({ version: 1, files }, null, 2)}
+`, "utf-8");
+    }
+    return staged.map((file) => file.relativePath);
+  };
+  const discard = async () => {
+    for (const file of staged) {
+      await rm(file.tempPath, { force: true }).catch(() => void 0);
+    }
+  };
+  return { stage, commit, discard };
+};
+export {
+  createOutputWriter
+};

package/dist/emit-examples.d.ts

@@ -1,4 +1,5 @@
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+import type { OutputWriter } from './create-output-writer.js';
 /**
  * Inputs for {@link emitExamples}. The schema and its root type name are the same
  * ones handed to the parser generator, so the arbitraries/examples line up with
@@ -7,8 +8,15 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
 export type EmitExamplesOptions = {
     readonly schema: JSONSchema;
     readonly rootTypeName: string;
-    /** Output root; example files always land under `<outputDir>/examples/`. */
-    readonly outputDir: string;
+    /**
+     * The run's writer, rooted at the output destination. Examples used to be
+     * written straight to disk with `mkdir` + `writeFile`, which meant the one
+     * output tree mjst emits that skipped the ownership check — a hand-written
+     * `examples/index.ts` was overwritten without a word. Taking the writer instead
+     * of a directory makes that impossible to reintroduce: there is no path here
+     * that does not go through staging, the manifest, and `--force`.
+     */
+    readonly writer: OutputWriter;
     /**
      * Nested location of the schema relative to `--schema-dir` (e.g. `api/order`),
      * mirrored beneath `examples/` so each schema's test data sits beside where its
@@ -21,8 +29,8 @@ export type EmitExamplesOptions = {
     readonly bannerPrefix?: string;
 };
 /**
- * Emits fast-check arbitrary + concrete example files for one schema into an
- * `examples/` subdirectory of `outputDir`.
+ * Stages fast-check arbitrary + concrete example files for one schema into an
+ * `examples/` subdirectory of the writer's root.
  *
  * The dedicated subdirectory keeps the test-data output from colliding with the
  * parser files, which otherwise share the same `<name>.ts` / `index.ts` names.
@@ -31,6 +39,9 @@ export type EmitExamplesOptions = {
  * barrel re-exports them. The arbitraries import `fast-check`, which consumers
  * must install as a (dev) dependency.
  *
- * @returns The written file paths, relative to `outputDir`.
+ * Nothing lands on disk until the caller commits the writer, so a schema that
+ * fails part-way through leaves no half-written `examples/` tree behind.
+ *
+ * @returns The staged file paths, relative to the writer's root.
  */
 export declare const emitExamples: (options: EmitExamplesOptions) => Promise<string[]>;

package/dist/emit-examples.js

@@ -1,18 +1,15 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, join, relative } from "node:path";
+import { join } from "node:path";
 import { buildExampleSchema } from "@amritk/generate-examples";
 const emitExamples = async (options) => {
-  const { schema, rootTypeName, outputDir, subDir = "", typeSuffix, bannerPrefix = "" } = options;
+  const { schema, rootTypeName, writer, subDir = "", typeSuffix, bannerPrefix = "" } = options;
   const files = await buildExampleSchema(schema, rootTypeName, typeSuffix);
-  const exampleDir = join(outputDir, "examples", subDir);
-  const written = [];
+  const staged = [];
   for (const file of files) {
-    const filePath = join(exampleDir, file.filename);
-    await mkdir(dirname(filePath), { recursive: true });
-    await writeFile(filePath, bannerPrefix + file.content, "utf-8");
-    written.push(relative(outputDir, filePath));
+    const relativePath = join("examples", subDir, file.filename);
+    await writer.stage(relativePath, bannerPrefix + file.content);
+    staged.push(relativePath);
   }
-  return written;
+  return staged;
 };
 export {
   emitExamples

package/dist/ensure-output-dir.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Creates the output directory, translating the two ways a path can already be
+ * taken by something that is not a directory into an actionable message.
+ *
+ * `mkdir --out-dir` on an existing *file* fails with a raw
+ * `EEXIST: file already exists, mkdir '/abs/path'` (and `ENOTDIR` when a file sits
+ * midway through the path), which reads like an mjst bug rather than "you pointed
+ * --out-dir at a file".
+ */
+export declare const ensureOutputDir: (dir: string) => Promise<void>;

package/dist/ensure-output-dir.js

@@ -0,0 +1,15 @@
+import { mkdir } from "node:fs/promises";
+const ensureOutputDir = async (dir) => {
+  try {
+    await mkdir(dir, { recursive: true });
+  } catch (error) {
+    const code = error.code;
+    if (code === "EEXIST" || code === "ENOTDIR") {
+      throw new Error(`Cannot use ${dir} as the output directory: a file already exists at that path.`);
+    }
+    throw error;
+  }
+};
+export {
+  ensureOutputDir
+};