@docentjs/cli 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nitish
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @docentjs/cli
+
+Command line tools for [Docent](https://github.com/FgrReloaded/docentjs) tour files.
+
+```sh
+npx @docentjs/cli validate "tours/*.json"
+```
+
+Or add it to a project and run it from scripts and CI:
+
+```sh
+pnpm add -D @docentjs/cli
+pnpm exec docent validate "tours/*.json"
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `docent validate <files...>` | Check tour files against the schema. Exits 1 when anything is wrong. |
+| `docent schema [file]` | Print the tour JSON Schema, or write it to a file. |
+
+Options: `--json` for machine-readable output, `--quiet` to print only problems, `--allow-unknown` to ignore unknown fields.
+
+A file may hold one tour or a list of tours.
+
+```
+tours/welcome.json
+✗ steps[0].arrow: "curvy" is not one of: caret, none, line, … Did you mean "curve"?
+! steps[1].titel: Unknown field, which Docent will ignore. Did you mean "title"?
+1 file checked: 1 error, 1 warning.
+```
+
+MIT

package/dist/cli.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { glob, readFile, writeFile } from "node:fs/promises";
+import { argv, exit, stdout } from "node:process";
+import { formatIssues, tourJsonSchema, validateTour } from "@docentjs/core/validate";
+//#region src/cli.ts
+/**
+* `docent` — check tour files without a browser.
+*
+* Tours are data, so they can be checked in a script, in CI, or by a tool
+* that writes them. This reports the same problems the library reports in
+* development, with the file and the path inside it.
+*/
+const HELP = `docent — tools for Docent tour files
+
+Usage
+  docent validate <files...>   Check tour files against the schema
+  docent schema [file]         Print the tour JSON Schema, or write it to a file
+
+Options
+  --json          Report as JSON, for other tools to read
+  --quiet         Print only problems, not the summary
+  --allow-unknown Ignore unknown fields instead of warning about them
+  -h, --help      Show this message
+
+Examples
+  docent validate tours/*.json
+  docent validate tours/welcome.tour.json --json
+  docent schema tour-schema.json
+`;
+async function main(args) {
+	const flags = new Set(args.filter((a) => a.startsWith("-")));
+	const [command, ...paths] = args.filter((a) => !a.startsWith("-"));
+	if (flags.has("-h") || flags.has("--help") || command === void 0 || command === "help") {
+		stdout.write(HELP);
+		return command === void 0 ? 1 : 0;
+	}
+	if (command === "schema") {
+		const json = `${JSON.stringify(tourJsonSchema(), null, 2)}\n`;
+		if (paths[0]) {
+			await writeFile(paths[0], json);
+			stdout.write(`Wrote ${paths[0]}\n`);
+		} else stdout.write(json);
+		return 0;
+	}
+	if (command !== "validate") {
+		stdout.write(`Unknown command "${command}".\n\n${HELP}`);
+		return 1;
+	}
+	if (paths.length === 0) {
+		stdout.write("Give at least one file to check, for example: docent validate tours/*.json\n");
+		return 1;
+	}
+	const files = await expand(paths);
+	if (files.length === 0) {
+		stdout.write(`No files matched ${paths.join(", ")}\n`);
+		return 1;
+	}
+	const reports = [];
+	for (const file of files) reports.push(await checkFile(file, { unknownFields: !flags.has("--allow-unknown") }));
+	if (flags.has("--json")) stdout.write(`${JSON.stringify(reports, null, 2)}\n`);
+	else stdout.write(report(reports, flags.has("--quiet")));
+	return reports.some((r) => r.failed !== void 0 || r.issues.some((i) => i.level === "error")) ? 1 : 0;
+}
+/** Expand any patterns, so quoted globs work the same in every shell. */
+async function expand(paths) {
+	const out = [];
+	for (const path of paths) {
+		if (!/[*?[]/.test(path)) {
+			out.push(path);
+			continue;
+		}
+		for await (const match of glob(path)) out.push(match);
+	}
+	return [...new Set(out)].sort();
+}
+/** One file, which may hold a single tour or a list of them. */
+async function checkFile(file, options) {
+	let text;
+	try {
+		text = await readFile(file, "utf8");
+	} catch {
+		return {
+			file,
+			issues: [],
+			failed: "Could not read this file."
+		};
+	}
+	let data;
+	try {
+		data = JSON.parse(text);
+	} catch (error) {
+		return {
+			file,
+			issues: [],
+			failed: `Not valid JSON: ${error.message}`
+		};
+	}
+	return {
+		file,
+		issues: (Array.isArray(data) ? data : [data]).flatMap((tour, index) => {
+			const found = validateTour(tour, options);
+			if (!Array.isArray(data)) return found;
+			return found.map((issue) => ({
+				...issue,
+				path: `[${index}]${issue.path ? `.${issue.path}` : ""}`
+			}));
+		})
+	};
+}
+function report(reports, quiet) {
+	const lines = [];
+	let errors = 0;
+	let warnings = 0;
+	for (const r of reports) {
+		if (r.failed) {
+			errors++;
+			lines.push(`${r.file}\n✗ ${r.failed}\n`);
+			continue;
+		}
+		errors += r.issues.filter((i) => i.level === "error").length;
+		warnings += r.issues.filter((i) => i.level === "warning").length;
+		if (r.issues.length > 0) lines.push(`${r.file}\n${formatIssues(r.issues)}\n`);
+	}
+	if (!quiet) {
+		const files = `${reports.length} file${reports.length === 1 ? "" : "s"}`;
+		lines.push(errors === 0 && warnings === 0 ? `${files} checked, no problems found.` : `${files} checked: ${errors} error${errors === 1 ? "" : "s"}, ${warnings} warning${warnings === 1 ? "" : "s"}.`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+exit(await main(argv.slice(2)));
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * `docent` — check tour files without a browser.\n *\n * Tours are data, so they can be checked in a script, in CI, or by a tool\n * that writes them. This reports the same problems the library reports in\n * development, with the file and the path inside it.\n */\n\nimport { glob, readFile, writeFile } from 'node:fs/promises'\nimport { argv, exit, stdout } from 'node:process'\nimport { formatIssues, type TourIssue, tourJsonSchema, validateTour } from '@docentjs/core/validate'\n\nconst HELP = `docent — tools for Docent tour files\n\nUsage\n  docent validate <files...>   Check tour files against the schema\n  docent schema [file]         Print the tour JSON Schema, or write it to a file\n\nOptions\n  --json          Report as JSON, for other tools to read\n  --quiet         Print only problems, not the summary\n  --allow-unknown Ignore unknown fields instead of warning about them\n  -h, --help      Show this message\n\nExamples\n  docent validate tours/*.json\n  docent validate tours/welcome.tour.json --json\n  docent schema tour-schema.json\n`\n\ninterface FileReport {\n  file: string\n  issues: TourIssue[]\n  /** Set when the file could not be read or parsed. */\n  failed?: string\n}\n\nasync function main(args: string[]): Promise<number> {\n  const flags = new Set(args.filter((a) => a.startsWith('-')))\n  const rest = args.filter((a) => !a.startsWith('-'))\n  const [command, ...paths] = rest\n\n  if (flags.has('-h') || flags.has('--help') || command === undefined || command === 'help') {\n    stdout.write(HELP)\n    return command === undefined ? 1 : 0\n  }\n\n  if (command === 'schema') {\n    const json = `${JSON.stringify(tourJsonSchema(), null, 2)}\\n`\n    if (paths[0]) {\n      await writeFile(paths[0], json)\n      stdout.write(`Wrote ${paths[0]}\\n`)\n    } else {\n      stdout.write(json)\n    }\n    return 0\n  }\n\n  if (command !== 'validate') {\n    stdout.write(`Unknown command \"${command}\".\\n\\n${HELP}`)\n    return 1\n  }\n\n  if (paths.length === 0) {\n    stdout.write('Give at least one file to check, for example: docent validate tours/*.json\\n')\n    return 1\n  }\n\n  const files = await expand(paths)\n  if (files.length === 0) {\n    stdout.write(`No files matched ${paths.join(', ')}\\n`)\n    return 1\n  }\n\n  const reports: FileReport[] = []\n  for (const file of files) {\n    reports.push(await checkFile(file, { unknownFields: !flags.has('--allow-unknown') }))\n  }\n\n  if (flags.has('--json')) {\n    stdout.write(`${JSON.stringify(reports, null, 2)}\\n`)\n  } else {\n    stdout.write(report(reports, flags.has('--quiet')))\n  }\n\n  const bad = reports.some(\n    (r) => r.failed !== undefined || r.issues.some((i) => i.level === 'error'),\n  )\n  return bad ? 1 : 0\n}\n\n/** Expand any patterns, so quoted globs work the same in every shell. */\nasync function expand(paths: string[]): Promise<string[]> {\n  const out: string[] = []\n  for (const path of paths) {\n    if (!/[*?[]/.test(path)) {\n      out.push(path)\n      continue\n    }\n    for await (const match of glob(path)) out.push(match)\n  }\n  return [...new Set(out)].sort()\n}\n\n/** One file, which may hold a single tour or a list of them. */\nasync function checkFile(file: string, options: { unknownFields: boolean }): Promise<FileReport> {\n  let text: string\n  try {\n    text = await readFile(file, 'utf8')\n  } catch {\n    return { file, issues: [], failed: 'Could not read this file.' }\n  }\n  let data: unknown\n  try {\n    data = JSON.parse(text)\n  } catch (error) {\n    return { file, issues: [], failed: `Not valid JSON: ${(error as Error).message}` }\n  }\n  const tours = Array.isArray(data) ? data : [data]\n  const issues = tours.flatMap((tour, index) => {\n    const found = validateTour(tour, options)\n    if (!Array.isArray(data)) return found\n    // Say which tour in the list, since the file holds several.\n    return found.map((issue) => ({\n      ...issue,\n      path: `[${index}]${issue.path ? `.${issue.path}` : ''}`,\n    }))\n  })\n  return { file, issues }\n}\n\nfunction report(reports: FileReport[], quiet: boolean): string {\n  const lines: string[] = []\n  let errors = 0\n  let warnings = 0\n  for (const r of reports) {\n    if (r.failed) {\n      errors++\n      lines.push(`${r.file}\\n✗ ${r.failed}\\n`)\n      continue\n    }\n    errors += r.issues.filter((i) => i.level === 'error').length\n    warnings += r.issues.filter((i) => i.level === 'warning').length\n    if (r.issues.length > 0) lines.push(`${r.file}\\n${formatIssues(r.issues)}\\n`)\n  }\n  if (!quiet) {\n    const files = `${reports.length} file${reports.length === 1 ? '' : 's'}`\n    lines.push(\n      errors === 0 && warnings === 0\n        ? `${files} checked, no problems found.`\n        : `${files} checked: ${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'}.`,\n    )\n  }\n  return `${lines.join('\\n')}\\n`\n}\n\nexit(await main(argv.slice(2)))\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@docentjs/cli",
+  "version": "0.7.0",
+  "description": "Command line tools for Docent: check tour files and print the tour JSON Schema.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FgrReloaded/docentjs.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/FgrReloaded/docentjs/tree/main/packages/cli#readme",
+  "bugs": {
+    "url": "https://github.com/FgrReloaded/docentjs/issues"
+  },
+  "keywords": [
+    "product-tour",
+    "guided-tour",
+    "onboarding",
+    "cli",
+    "docent"
+  ],
+  "type": "module",
+  "bin": {
+    "docent": "./dist/cli.mjs"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@docentjs/core": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "tsdown": "^0.23.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}