@trail-cli/cli 0.1.0

package/bin/trail.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { register } from "tsx/esm/api";
+
+register();
+await import("../src/cli.ts");

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@trail-cli/cli",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ndivhomakhuvha/trail.git"
+  },
+  "type": "module",
+  "bin": {
+    "trail": "./bin/trail.js"
+  },
+  "files": [
+    "bin",
+    "src/cli.ts",
+    "src/build.ts",
+    "src/preview.ts",
+    "src/validate.ts"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@trail-cli/guide-schema": "workspace:*",
+    "commander": "^12.1.0",
+    "tsx": "^4.19.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.15",
+    "typescript": "^5.5.4"
+  }
+}

package/src/build.ts

@@ -0,0 +1,57 @@
+import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { REPO_ROOT, resolveDiscoveredGuides } from "./validate.js";
+
+const OUTPUT_ROOT = path.join(REPO_ROOT, "dist", "releases");
+
+export interface BuildOptions {
+  guidesRoot?: string;
+  outputRoot?: string;
+}
+
+export function runBuild(options: BuildOptions = {}): void {
+  const outputRoot = options.outputRoot ?? OUTPUT_ROOT;
+  const guidesRoot = options.guidesRoot;
+  const guides = resolveDiscoveredGuides(guidesRoot);
+
+  if (guides.length === 0) {
+    rmSync(outputRoot, { recursive: true, force: true });
+    console.log(`No guides found under ${guidesRoot ?? "guides/releases/"}.`);
+    return;
+  }
+
+  const failures = guides.filter((result) => !result.success);
+
+  if (failures.length > 0) {
+    for (const result of failures) {
+      console.error(`✗ ${result.source.release}/${result.source.file}`);
+      for (const issue of result.issues) {
+        console.error(`  ${issue.path}: ${issue.message}`);
+      }
+    }
+
+    console.log("");
+    console.error("Build failed: one or more guides are invalid.");
+    process.exitCode = 1;
+    return;
+  }
+
+  mkdirSync(path.dirname(outputRoot), { recursive: true });
+  const stagingRoot = mkdtempSync(`${outputRoot}.tmp-`);
+
+  for (const result of guides) {
+    if (!result.success) continue;
+
+    const outDir = path.join(stagingRoot, result.source.release);
+    mkdirSync(outDir, { recursive: true });
+    const outFile = path.join(outDir, `${result.guide.id}.json`);
+    writeFileSync(outFile, JSON.stringify(result.guide, null, 2));
+    console.log(`✓ built ${result.source.release}/${path.basename(outFile)}`);
+  }
+
+  rmSync(outputRoot, { recursive: true, force: true });
+  renameSync(stagingRoot, outputRoot);
+
+  console.log("");
+  console.log(`Built ${guides.length} guide(s) to ${outputRoot}.`);
+}

package/src/cli.ts

@@ -0,0 +1,25 @@
+import { Command } from "commander";
+import { runValidate } from "./validate.js";
+import { runBuild } from "./build.js";
+import { runPreview } from "./preview.js";
+
+const program = new Command();
+
+program.name("trail").description("Trail CLI").version("0.1.0");
+
+program
+  .command("validate")
+  .description("Validate all YAML guides under guides/releases/")
+  .action(() => runValidate());
+
+program
+  .command("build")
+  .description("Convert YAML guides into static JSON assets under dist/releases/")
+  .action(() => runBuild());
+
+program
+  .command("preview")
+  .description("Start a local preview server for the viewer")
+  .action(() => runPreview());
+
+program.parse(process.argv);

package/src/preview.ts

@@ -0,0 +1,18 @@
+import { spawn } from "node:child_process";
+import { REPO_ROOT } from "./validate.js";
+
+export function runPreview(): void {
+  console.log("Starting local preview server...");
+  console.log("Example: http://localhost:5173/g/2026.08.26/PAY-1245");
+  console.log("");
+
+  const child = spawn("pnpm", ["--filter", "@trail-cli/viewer", "dev"], {
+    cwd: REPO_ROOT,
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+
+  child.on("exit", (code) => {
+    process.exitCode = code ?? 0;
+  });
+}

package/src/validate.ts

@@ -0,0 +1,137 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  parseAuthorGuideYaml,
+  resolveGuide,
+  type AuthorGuide,
+  type Guide,
+  type GuideValidationIssue,
+} from "@trail-cli/guide-schema";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(here, "../../../");
+export const GUIDES_ROOT = path.join(REPO_ROOT, "guides", "releases");
+
+export interface DiscoveredGuide {
+  release: string;
+  file: string;
+  filePath: string;
+}
+
+/** Walks `guides/releases/<release>/*.yaml`. Returns an empty list if the directory doesn't exist. */
+export function discoverGuides(guidesRoot = GUIDES_ROOT): DiscoveredGuide[] {
+  if (!existsSync(guidesRoot)) return [];
+
+  const guides: DiscoveredGuide[] = [];
+  const releases = readdirSync(guidesRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+
+  for (const release of releases) {
+    const releaseDir = path.join(guidesRoot, release.name);
+    const files = readdirSync(releaseDir).filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"));
+    for (const file of files.sort()) {
+      guides.push({ release: release.name, file, filePath: path.join(releaseDir, file) });
+    }
+  }
+
+  return guides;
+}
+
+export interface ValidationResult {
+  file: string;
+  success: boolean;
+  issues?: GuideValidationIssue[];
+}
+
+export type ResolvedGuideResult =
+  | { source: DiscoveredGuide; success: true; guide: Guide }
+  | { source: DiscoveredGuide; success: false; issues: GuideValidationIssue[] };
+
+/** Parses and resolves all guides per release, so extensions can only reference local bases. */
+export function resolveDiscoveredGuides(guidesRoot = GUIDES_ROOT): ResolvedGuideResult[] {
+  const parsed = discoverGuides(guidesRoot).map((source) => ({
+    source,
+    result: parseAuthorGuideYaml(readFileSync(source.filePath, "utf-8")),
+  }));
+  const releases = new Map<string, typeof parsed>();
+  for (const entry of parsed) {
+    const release = releases.get(entry.source.release) ?? [];
+    release.push(entry);
+    releases.set(entry.source.release, release);
+  }
+
+  const results: ResolvedGuideResult[] = [];
+  for (const [release, entries] of releases) {
+    const guidesById = new Map<string, AuthorGuide>();
+    const duplicateIds = new Set<string>();
+    for (const { result } of entries) {
+      if (!result.success) continue;
+      if (guidesById.has(result.guide.id)) duplicateIds.add(result.guide.id);
+      else guidesById.set(result.guide.id, result.guide);
+    }
+
+    for (const { source, result } of entries) {
+      if (!result.success) {
+        results.push({ source, success: false, issues: result.issues });
+      } else if (duplicateIds.has(result.guide.id)) {
+        results.push({
+          source,
+          success: false,
+          issues: [{ path: "id", message: `Duplicate guide id in release ${release}: ${result.guide.id}.` }],
+        });
+      } else {
+        const resolved = resolveGuide(result.guide, guidesById);
+        results.push(
+          resolved.success
+            ? { source, success: true, guide: resolved.guide }
+            : { source, success: false, issues: resolved.issues },
+        );
+      }
+    }
+  }
+  return results;
+}
+
+export function validateGuides(): { results: ValidationResult[] } {
+  const results = resolveDiscoveredGuides().map((result): ValidationResult => {
+    const file = `${result.source.release}/${result.source.file}`;
+    return result.success ? { file, success: true } : { file, success: false, issues: result.issues };
+  });
+  return { results };
+}
+
+export function runValidate(): void {
+  const { results } = validateGuides();
+
+  if (results.length === 0) {
+    console.log("No guides found under guides/releases/.");
+    return;
+  }
+
+  const failures = results.filter((r) => !r.success);
+
+  for (const result of results) {
+    if (result.success) {
+      console.log(`✓ ${result.file}`);
+    }
+  }
+
+  if (failures.length > 0) {
+    for (const failure of failures) {
+      console.log("");
+      console.log(`✗ ${failure.file}`);
+      console.log("");
+      for (const issue of failure.issues ?? []) {
+        console.log(`${issue.path}:`);
+        console.log(issue.message);
+      }
+    }
+    console.log("");
+    console.error(`${failures.length} of ${results.length} guide(s) invalid.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log("");
+  console.log(`${results.length} guides valid.`);
+}