@markdstage/markdstage 0.1.1

package/src/commands/skill.mjs

@@ -0,0 +1,114 @@
+// markdstage skill — install or check portable Agent Skills.
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { UsageError } from "../exit.mjs";
+import { SKILL_TARGETS, buildSkillFiles } from "../skills.mjs";
+
+export const SKILL_TARGET_NAMES = Object.keys(SKILL_TARGETS);
+
+function resolveTargets(target) {
+  if (!target || target === "all") return SKILL_TARGET_NAMES;
+  const names = target
+    .split(",")
+    .map((name) => name.trim())
+    .filter(Boolean);
+  for (const name of names) {
+    if (!SKILL_TARGETS[name]) {
+      throw new UsageError(
+        `Unknown skill target: ${name}. Available targets: ${SKILL_TARGET_NAMES.join(", ")}, all.`,
+      );
+    }
+  }
+  return names;
+}
+
+export function skillDirectory(root, target) {
+  return path.join(root, ...SKILL_TARGETS[target].directory);
+}
+
+async function readIfExists(file) {
+  try {
+    return await readFile(file, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/**
+ * Install or verify generated skill files.
+ *
+ * `check` reports drift without writing. Without `force`, files that already
+ * exist with different contents are reported as `conflict` and left untouched.
+ */
+export async function skillCommand({
+  action = "install",
+  target,
+  root = process.cwd(),
+  force = false,
+} = {}) {
+  if (action !== "install" && action !== "check") {
+    throw new UsageError(
+      `Unknown skill action: ${action}. Available actions: install, check.`,
+    );
+  }
+  const targets = resolveTargets(target);
+  const results = [];
+  let conflicts = 0;
+  let changed = 0;
+
+  for (const name of targets) {
+    const directory = skillDirectory(root, name);
+    const files = await buildSkillFiles(name);
+    for (const [relative, contents] of files) {
+      const file = path.join(directory, ...relative.split("/"));
+      const existing = await readIfExists(file);
+      let status;
+      if (existing === contents) {
+        status = "unchanged";
+      } else if (existing === null) {
+        status = "created";
+      } else if (force || action === "check") {
+        status = "updated";
+      } else {
+        status = "conflict";
+      }
+      if (status === "conflict") conflicts += 1;
+      if (status === "created" || status === "updated") changed += 1;
+      if (action === "install" && (status === "created" || status === "updated")) {
+        await mkdir(path.dirname(file), { recursive: true });
+        await writeFile(file, contents, "utf8");
+      }
+      results.push({ target: name, path: file, status });
+    }
+  }
+
+  return { action, targets, files: results, changed, conflicts };
+}
+
+export function formatSkillReport(report) {
+  const lines = [];
+  for (const file of report.files) {
+    if (file.status === "unchanged") continue;
+    lines.push(`  ${file.status.padEnd(9)} ${file.path}`);
+  }
+  if (report.action === "check") {
+    lines.unshift(
+      report.changed || report.conflicts
+        ? `Generated skills are out of date (${report.changed} file(s) differ).`
+        : "Generated skills are up to date.",
+    );
+    return lines.join("\n");
+  }
+  lines.unshift(
+    `Installed skills for ${report.targets.join(", ")} (${report.changed} file(s) written).`,
+  );
+  if (report.conflicts) {
+    lines.push(
+      `${report.conflicts} file(s) were modified locally and were left untouched. Re-run with --force to overwrite.`,
+    );
+  }
+  return lines.join("\n");
+}

package/src/commands/validate.mjs

@@ -0,0 +1,79 @@
+// markdstage validate — check deck structure, Architecture DSL, and themes.
+
+import {
+  MarkdStageError,
+  architectureValidationErrors,
+  createDeckSession,
+  createUrlToken,
+  hasFrontMatter,
+} from "../runtime.mjs";
+
+export async function validateCommand(options) {
+  const errors = [];
+  const warnings = [];
+  let session = null;
+
+  try {
+    session = await createDeckSession({
+      file: options.file,
+      workspaceRoot: options.workspace,
+      theme: options.theme,
+      themeFile: options.themeFile,
+      assetUrlPrefix: `/${createUrlToken()}/theme-assets/`,
+    });
+  } catch (error) {
+    if (!(error instanceof MarkdStageError)) throw error;
+    errors.push({
+      code: error.code,
+      message: error.message,
+    });
+    return { ok: false, file: options.file, total: 0, errors, warnings };
+  }
+
+  for (const issue of architectureValidationErrors(session.slides)) {
+    errors.push({
+      code: issue.code,
+      page: issue.page,
+      architecture: issue.architecture,
+      message: issue.message,
+    });
+  }
+
+  session.slides.forEach((slide, index) => {
+    if (!hasFrontMatter(slide)) {
+      warnings.push({
+        code: "missing_front_matter",
+        page: index + 1,
+        message:
+          "Front matter is missing. Add the deck/layout/page/total/size fields to the leading --- block.",
+      });
+    }
+  });
+
+  return {
+    ok: errors.length === 0,
+    file: session.file,
+    workspace: session.workspaceRoot,
+    total: session.slides.length,
+    theme: session.theme,
+    themeFile: session.customThemeFile || undefined,
+    errors,
+    warnings,
+  };
+}
+
+export function formatValidateReport(report) {
+  const lines = [];
+  lines.push(`${report.file}`);
+  if (report.total) lines.push(`  slides: ${report.total}${report.theme ? `, theme: ${report.theme}` : ""}`);
+  for (const error of report.errors) {
+    lines.push(
+      `  error  ${error.page ? `slide ${error.page}: ` : ""}${error.message} (${error.code})`,
+    );
+  }
+  for (const warning of report.warnings) {
+    lines.push(`  warn   slide ${warning.page}: ${warning.message}`);
+  }
+  lines.push(report.ok ? "  OK: the deck is valid." : `  ${report.errors.length} error(s) found.`);
+  return lines.join("\n");
+}

package/src/deck.mjs

@@ -0,0 +1,63 @@
+// Deck lifecycle helpers shared by the CLI commands.
+
+import {
+  createDeckSession,
+  createUrlToken,
+  startPresentationServer,
+} from "./runtime.mjs";
+
+/**
+ * Open a deck, start its loopback presentation server, and hand both to `run`.
+ * The server is always closed again, including on failure.
+ */
+export async function withDeckServer(options, run) {
+  const token = createUrlToken();
+  const session = await createDeckSession({
+    file: options.file,
+    workspaceRoot: options.workspace,
+    theme: options.theme,
+    themeFile: options.themeFile,
+    assetUrlPrefix: `/${token}/theme-assets/`,
+    log: options.log,
+  });
+  const server = await startPresentationServer(session, {
+    token,
+    onLog: options.log,
+  });
+  try {
+    return await run(session, server);
+  } finally {
+    await server.close();
+  }
+}
+
+export function parsePageList(value, { total } = {}) {
+  const entries = String(value)
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  const indexes = [];
+  for (const entry of entries) {
+    const range = entry.match(/^(\d+)\s*-\s*(\d+)$/);
+    if (range) {
+      const from = Number.parseInt(range[1], 10);
+      const to = Number.parseInt(range[2], 10);
+      if (!Number.isInteger(from) || !Number.isInteger(to) || from < 1 || to < from) {
+        throw new RangeError(`Invalid page range: ${entry}`);
+      }
+      for (let page = from; page <= to; page += 1) indexes.push(page - 1);
+      continue;
+    }
+    const page = Number.parseInt(entry, 10);
+    if (!Number.isInteger(page) || page < 1 || String(page) !== entry) {
+      throw new RangeError(`Invalid page number: ${entry}`);
+    }
+    indexes.push(page - 1);
+  }
+  const unique = [...new Set(indexes)].sort((a, b) => a - b);
+  if (!unique.length) throw new RangeError("At least one page is required.");
+  if (total !== undefined && unique.some((index) => index >= total)) {
+    throw new RangeError(`Pages must be between 1 and ${total}.`);
+  }
+  return unique;
+}

package/src/exit.mjs

@@ -0,0 +1,58 @@
+// Stable exit codes and error formatting for the MarkdStage CLI.
+
+export const EXIT_OK = 0;
+export const EXIT_USAGE = 1;
+export const EXIT_DECK = 2;
+export const EXIT_ENVIRONMENT = 3;
+export const EXIT_FAILURE = 4;
+export const EXIT_ISSUES = 5;
+
+export const EXIT_CODES = {
+  0: "success",
+  1: "usage error",
+  2: "deck or input error",
+  3: "environment error (no Chromium-based browser)",
+  4: "rendering or output failure",
+  5: "layout or validation issues were found",
+};
+
+const DECK_ERROR_CODES = new Set([
+  "empty_markdown",
+  "file_not_found",
+  "file_too_large",
+  "invalid_input",
+  "invalid_markdown_path",
+  "invalid_output_path",
+  "invalid_theme_file",
+  "no_deck",
+  "path_outside_workspace",
+  "slide_out_of_range",
+  "theme_file_not_found",
+  "too_many_slides",
+]);
+
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+    this.code = "usage_error";
+  }
+}
+
+export function exitCodeFor(error) {
+  if (error instanceof UsageError) return EXIT_USAGE;
+  const code = error?.code;
+  if (typeof code === "string") {
+    if (code.endsWith("browser_not_found")) return EXIT_ENVIRONMENT;
+    if (DECK_ERROR_CODES.has(code)) return EXIT_DECK;
+  }
+  return EXIT_FAILURE;
+}
+
+export function errorPayload(error) {
+  return {
+    ok: false,
+    error: typeof error?.code === "string" ? error.code : "unexpected_error",
+    message: error?.message || String(error),
+  };
+}

package/src/runtime.mjs

@@ -0,0 +1,77 @@
+// Resolve and load the shared MarkdStage runtime.
+//
+// Published packages carry the runtime in `shared/` (populated by
+// scripts/sync-shared.mjs at pack time). In a repository checkout the CLI falls
+// back to the canonical Extension folder so both paths run the very same
+// parser, renderer, validation, and output implementations.
+
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const BUNDLED_ROOT = join(PACKAGE_ROOT, "shared");
+const CHECKOUT_ROOT = resolve(
+  PACKAGE_ROOT,
+  "..",
+  "..",
+  ".github",
+  "extensions",
+  "markdstage",
+);
+
+export const SHARED_ROOT = existsSync(join(BUNDLED_ROOT, "markdown-deck.mjs"))
+  ? BUNDLED_ROOT
+  : CHECKOUT_ROOT;
+
+if (!existsSync(join(SHARED_ROOT, "markdown-deck.mjs"))) {
+  throw new Error(
+    "The MarkdStage shared runtime is missing. Reinstall the package or run `npm run sync`.",
+  );
+}
+
+export function sharedPath(...parts) {
+  return join(SHARED_ROOT, ...parts);
+}
+
+function load(relativePath) {
+  return import(pathToFileURL(sharedPath(relativePath)).href);
+}
+
+const [
+  errors,
+  deckSession,
+  presentationServer,
+  output,
+  browser,
+  outputPaths,
+  guide,
+  presenterWindow,
+  markdownFiles,
+] = await Promise.all([
+  load("runtime/errors.mjs"),
+  load("runtime/deck-session.mjs"),
+  load("runtime/presentation-server.mjs"),
+  load("runtime/output.mjs"),
+  load("runtime/browser.mjs"),
+  load("runtime/output-paths.mjs"),
+  load("markdstage-guide.mjs"),
+  load("presenter-window.mjs"),
+  load("scripts/markdown-files.mjs"),
+]);
+
+export const { MarkdStageError } = errors;
+export const { createDeckSession, readDeckSlides, resolveDeckFile, resolveDeckTheme } =
+  deckSession;
+export const { createUrlToken, startPresentationServer } = presentationServer;
+export const { captureSlides, exportPdf, inspectLayout, MAX_CAPTURE_SLIDES } = output;
+export const { findChromiumBrowser, terminateProcessTree, isProcessRunning } = browser;
+export const { captureDirectoryName, pdfNameForSource } = outputPaths;
+export const {
+  architectureValidationErrors,
+  deckValidationFeedback,
+  hasFrontMatter,
+  readGuide,
+} = guide;
+export const { buildPresenterBrowserArgs } = presenterWindow;
+export const { isMarkdownPath, MARKDOWN_MAX_BYTES } = markdownFiles;

package/src/skills.mjs

@@ -0,0 +1,155 @@
+// Portable Agent Skill generation.
+//
+// Every reference file is generated from readGuide(topic) so the skills cannot
+// drift from the canonical MarkdStage documentation. The generated tree follows
+// the Agent Skills specification: a SKILL.md with YAML front matter (name +
+// description) plus progressive-disclosure reference files.
+
+import { GUIDE_TOPICS } from "./commands/guide.mjs";
+import { readGuide } from "./runtime.mjs";
+
+export const SKILL_TARGETS = {
+  codex: {
+    label: "Codex",
+    directory: [".agents", "skills", "markdstage"],
+  },
+  claude: {
+    label: "Claude Code",
+    directory: [".claude", "skills", "markdstage"],
+  },
+  copilot: {
+    label: "GitHub Copilot",
+    directory: [".github", "skills", "markdstage"],
+  },
+};
+
+const DESCRIPTION =
+  "Turn Markdown into 16:9 slides with the MarkdStage CLI. Use when the user " +
+  'asks to present, preview, validate, screenshot, or export a Markdown deck ("present slides.md", ' +
+  '"turn this file into slides", "export the deck to PDF", "check whether my slides fit"). ' +
+  "Provides deterministic commands for presenting in a browser, validating Architecture DSL and " +
+  "themes, inspecting 1280x720 clipping, capturing PNGs, and exporting PDF.";
+
+function frontMatter(fields) {
+  const lines = ["---"];
+  for (const [key, value] of Object.entries(fields)) {
+    lines.push(`${key}: ${JSON.stringify(value)}`);
+  }
+  lines.push("---");
+  return lines.join("\n");
+}
+
+function canvasNote(target) {
+  if (target !== "copilot") return "";
+  return [
+    "",
+    "## Canvas adapter",
+    "",
+    "Inside GitHub Copilot with the MarkdStage canvas Extension installed, prefer the",
+    "canvas: pass every slide to the `open` input of canvas ID `MarkdStage` and let the",
+    "canvas controls handle navigation. Use the CLI commands below when the canvas is not",
+    "available, or for validation, PNG capture, and PDF export in a terminal or CI job.",
+  ].join("\n");
+}
+
+function skillBody(target) {
+  const label = SKILL_TARGETS[target].label;
+  return `# MarkdStage
+
+Markdown is the single source of truth. MarkdStage renders each Markdown fragment
+between \`---\` separators as one 1280x720 (16:9) slide, and the CLI renders exactly
+what the MarkdStage canvas and MarkdStage Desktop render.
+
+## Requirements
+
+- Node.js 24 or later.
+- An installed Microsoft Edge, Google Chrome, or Chromium (never downloaded automatically).
+- The CLI: \`npx @markdstage/markdstage <command>\` or \`npm install --global @markdstage/markdstage\`.
+
+## Workflow
+
+1. Write or edit the deck as one Markdown file (see \`references/slide-format.md\`).
+2. Validate it: \`markdstage validate slides.md --json\`.
+3. Check the fixed 16:9 layout: \`markdstage inspect slides.md --json\`.
+4. Capture clipped slides for review: \`markdstage capture slides.md\`.
+5. Present or export: \`markdstage present slides.md --watch\` / \`markdstage export slides.md\`.
+
+Never hand-write HTML or CSS for a slide. Fix layout problems by shortening the
+content or by changing the layout in front matter.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| \`markdstage present <file> [--watch]\` | Serve the deck on loopback and open it in a browser window. \`--watch\` reloads on save and keeps the current slide. |
+| \`markdstage validate <file> [--json]\` | Check deck structure, Architecture DSL blocks, and themes. |
+| \`markdstage inspect <file> [--json]\` | Report 1280x720 clipping diagnostics for the deck or one slide. |
+| \`markdstage capture <file> [--pages 2,4]\` | Write 1280x720 PNG files; without \`--pages\` only clipped slides are captured. |
+| \`markdstage export <file> [--output slides.pdf]\` | Produce the 16:9 PDF. |
+| \`markdstage guide <topic>\` | Print the canonical MarkdStage authoring guide. |
+
+Exit codes: \`0\` success, \`1\` usage error, \`2\` deck or input error, \`3\` no
+Chromium-based browser, \`4\` rendering failure, \`5\` issues found with \`--fail-on-issues\`.
+
+## References
+
+Read the reference that matches the task before writing Markdown:
+
+- \`references/slide-format.md\` — slide fragments, front matter, layouts.
+- \`references/themes.md\` — built-in themes.
+- \`references/custom-themes.md\` — custom theme authoring and \`theme-file\`.
+- \`references/theme-schema.md\` — custom theme properties.
+- \`references/architecture-dsl.md\` — Architecture DSL v1 diagrams.
+- \`references/architecture-schema.md\` — Architecture DSL schema summary.
+- \`references/overview.md\` — how MarkdStage works.
+
+## Notes for ${label}
+
+Run the CLI through the shell. Presentation servers bind to loopback with an
+unguessable per-process URL token, and every generated file stays inside the
+workspace.${canvasNote(target)}
+`;
+}
+
+const REFERENCE_HEADERS = {
+  overview: "MarkdStage overview",
+  "slide-format": "Slide fragment format",
+  themes: "Built-in themes",
+  "custom-themes": "Custom theme authoring",
+  "theme-schema": "Custom theme schema",
+  "architecture-dsl": "Architecture DSL v1",
+  "architecture-schema": "Architecture DSL schema summary",
+};
+
+/**
+ * Build every file of the generated skill as a `path -> contents` map.
+ * Paths use POSIX separators and are relative to the skill directory.
+ */
+export async function buildSkillFiles(target) {
+  if (!SKILL_TARGETS[target]) {
+    throw new Error(`Unknown skill target: ${target}`);
+  }
+  const files = new Map();
+  files.set(
+    "SKILL.md",
+    `${frontMatter({
+      name: "markdstage",
+      description: DESCRIPTION,
+      license: "MIT",
+    })}\n\n${skillBody(target)}`,
+  );
+  for (const topic of GUIDE_TOPICS) {
+    const content = (await readGuide(topic)).trim();
+    const parts = [
+      "<!-- Generated by `markdstage skill install`. Do not edit by hand. -->",
+      `<!-- Source: markdstage_guide topic "${topic}" -->`,
+      "",
+    ];
+    if (!content.startsWith("#")) {
+      parts.push(`# ${REFERENCE_HEADERS[topic]}`, "");
+    }
+    parts.push(content, "");
+    files.set(`references/${topic}.md`, parts.join("\n"));
+  }
+  return files;
+}