stego-cli 0.4.2 → 0.5.0

package/dist/stego-cli/src/modules/compile/domain/image-settings.js

@@ -0,0 +1,394 @@
+import path from "node:path";
+import { IMAGE_GLOBAL_KEYS, asPlainRecord, cloneImageStyle, extractImageDestinationTarget, inferEffectiveImageLayout, isExternalImageTarget, isImageStyleEmpty, mergeImageStyles, normalizeImageAttrs, normalizeImageClasses, normalizeImagePathKey, normalizeImageScalar, stripImageQueryAndAnchor } from "../../../../../shared/src/domain/images/index.js";
+export function parseProjectImageDefaults(projectMeta) {
+    const warnings = [];
+    const global = {};
+    const overrides = new Map();
+    const rawImages = projectMeta.images;
+    const imagesRecord = asPlainRecord(rawImages);
+    if (rawImages == null) {
+        return { global, overrides, warnings };
+    }
+    if (!imagesRecord) {
+        warnings.push("Project 'images' must be an object.");
+        return { global, overrides, warnings };
+    }
+    for (const [key, value] of Object.entries(imagesRecord)) {
+        if (IMAGE_GLOBAL_KEYS.has(key)) {
+            applyImageStyleField(global, key, value, `project.images.${key}`, warnings);
+            continue;
+        }
+        warnings.push(`Project image defaults do not support key 'images.${key}'. Use only width, height, classes, id, attrs, layout, align in stego-project.json.`);
+    }
+    return { global, overrides, warnings };
+}
+export function parseManuscriptImageOverrides(frontmatter) {
+    const warnings = [];
+    const global = {};
+    const overrides = new Map();
+    const rawImages = frontmatter.images;
+    const imagesRecord = asPlainRecord(rawImages);
+    if (rawImages == null) {
+        return { global, overrides, warnings };
+    }
+    if (!imagesRecord) {
+        warnings.push("Metadata 'images' must be an object.");
+        return { global, overrides, warnings };
+    }
+    for (const [key, value] of Object.entries(imagesRecord)) {
+        if (IMAGE_GLOBAL_KEYS.has(key)) {
+            warnings.push(`Manuscript frontmatter 'images.${key}' is reserved for project defaults. Put defaults in stego-project.json 'images.${key}'.`);
+            continue;
+        }
+        const styleRecord = asPlainRecord(value);
+        if (!styleRecord) {
+            warnings.push(`Metadata 'images.${key}' must be an object of style keys (width, height, classes, id, attrs, layout, align).`);
+            continue;
+        }
+        const style = {};
+        for (const [styleKey, styleValue] of Object.entries(styleRecord)) {
+            applyImageStyleField(style, styleKey, styleValue, `images.${key}.${styleKey}`, warnings);
+        }
+        overrides.set(normalizeImagePathKey(key), style);
+    }
+    return { global, overrides, warnings };
+}
+export function rewriteMarkdownImagesForChapter(input) {
+    const projectDefaults = parseProjectImageDefaults(input.projectMeta);
+    const manuscriptOverrides = parseManuscriptImageOverrides(input.frontmatter);
+    const settings = {
+        global: projectDefaults.global,
+        overrides: manuscriptOverrides.overrides,
+        warnings: [...projectDefaults.warnings, ...manuscriptOverrides.warnings]
+    };
+    if (isImageStyleEmpty(settings.global) && settings.overrides.size === 0) {
+        return input.body;
+    }
+    const lineEnding = input.body.includes("\r\n") ? "\r\n" : "\n";
+    const lines = input.body.split(/\r?\n/);
+    const rewritten = [];
+    let openFence = null;
+    const chapterDir = path.dirname(input.chapterPath);
+    const assetsDir = path.resolve(input.projectRoot, "assets");
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        const fenceMatch = trimmed.match(/^(```+|~~~+)/);
+        if (fenceMatch) {
+            const marker = fenceMatch[1][0];
+            const length = fenceMatch[1].length;
+            if (!openFence) {
+                openFence = { marker, length };
+            }
+            else if (openFence.marker === marker && length >= openFence.length) {
+                openFence = null;
+            }
+            rewritten.push(line);
+            continue;
+        }
+        if (openFence) {
+            rewritten.push(line);
+            continue;
+        }
+        rewritten.push(rewriteImagesInLine(line, {
+            settings,
+            chapterDir,
+            projectRoot: input.projectRoot,
+            assetsDir
+        }));
+    }
+    return rewritten.join(lineEnding);
+}
+function rewriteImagesInLine(line, context) {
+    const imageRegex = /!\[([^\]]*)\]\(([^)]+)\)(\s*\{[^{}]*\})?/g;
+    return line.replace(imageRegex, (_full, altText, destination, inlineAttrText) => {
+        const parsedDestination = extractImageDestinationTarget(destination);
+        if (!parsedDestination || isExternalImageTarget(parsedDestination) || parsedDestination.startsWith("#")) {
+            return _full;
+        }
+        const cleanTarget = stripImageQueryAndAnchor(parsedDestination);
+        if (!cleanTarget) {
+            return _full;
+        }
+        const resolvedPath = path.resolve(context.chapterDir, cleanTarget);
+        if (!isPathInside(resolvedPath, context.assetsDir)) {
+            return _full;
+        }
+        const relativeToProject = path.relative(context.projectRoot, resolvedPath);
+        if (!relativeToProject || relativeToProject.startsWith("..") || path.isAbsolute(relativeToProject)) {
+            return _full;
+        }
+        const projectKey = normalizeImagePathKey(relativeToProject);
+        const effectiveStyle = buildEffectiveStyle(context.settings, projectKey);
+        if (isImageStyleEmpty(effectiveStyle)) {
+            return _full;
+        }
+        const inlineStyle = parseInlineAttrList(inlineAttrText?.trim());
+        const merged = mergeStyle(effectiveStyle, inlineStyle);
+        const renderedAttrList = renderAttrList(merged);
+        return `![${altText}](${destination})${renderedAttrList}`;
+    });
+}
+function buildEffectiveStyle(settings, projectRelativeKey) {
+    const merged = cloneImageStyle(settings.global);
+    const override = settings.overrides.get(projectRelativeKey);
+    if (override) {
+        return mergeStyle(merged, override);
+    }
+    return merged;
+}
+function mergeStyle(base, next) {
+    const merged = mergeImageStyles(base, next);
+    if (next.width) {
+        if (merged.attrs && Object.hasOwn(merged.attrs, "width")) {
+            merged.attrs.width = next.width;
+        }
+    }
+    if (next.height) {
+        if (merged.attrs && Object.hasOwn(merged.attrs, "height")) {
+            merged.attrs.height = next.height;
+        }
+    }
+    if (next.layout) {
+        if (merged.attrs && Object.hasOwn(merged.attrs, "data-layout")) {
+            merged.attrs["data-layout"] = next.layout;
+        }
+    }
+    if (next.align) {
+        if (merged.attrs && Object.hasOwn(merged.attrs, "data-align")) {
+            merged.attrs["data-align"] = next.align;
+        }
+    }
+    return merged;
+}
+function parseInlineAttrList(rawAttrText) {
+    if (!rawAttrText) {
+        return {};
+    }
+    const text = rawAttrText.trim();
+    if (!text.startsWith("{") || !text.endsWith("}")) {
+        return {};
+    }
+    const body = text.slice(1, -1).trim();
+    if (!body) {
+        return {};
+    }
+    const style = {};
+    const attrs = {};
+    const classes = [];
+    for (const token of splitAttrTokens(body)) {
+        if (!token) {
+            continue;
+        }
+        if (token.startsWith("#")) {
+            const id = token.slice(1).trim();
+            if (id) {
+                style.id = id;
+            }
+            continue;
+        }
+        if (token.startsWith(".")) {
+            const className = token.slice(1).trim();
+            if (className) {
+                classes.push(className);
+            }
+            continue;
+        }
+        const equalsIndex = token.indexOf("=");
+        if (equalsIndex <= 0) {
+            continue;
+        }
+        const key = token.slice(0, equalsIndex).trim();
+        const value = stripWrappingQuotes(token.slice(equalsIndex + 1).trim());
+        if (!key || !value) {
+            continue;
+        }
+        if (key === "width") {
+            style.width = value;
+            continue;
+        }
+        if (key === "height") {
+            style.height = value;
+            continue;
+        }
+        if (key === "layout") {
+            if (value === "block" || value === "inline") {
+                style.layout = value;
+            }
+            continue;
+        }
+        if (key === "align") {
+            if (value === "left" || value === "center" || value === "right") {
+                style.align = value;
+            }
+            continue;
+        }
+        attrs[key] = value;
+    }
+    if (classes.length > 0) {
+        style.classes = classes;
+    }
+    if (Object.keys(attrs).length > 0) {
+        style.attrs = attrs;
+    }
+    return style;
+}
+function splitAttrTokens(value) {
+    const tokens = [];
+    let current = "";
+    let quote = null;
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index];
+        if (quote) {
+            current += char;
+            if (char === quote && value[index - 1] !== "\\") {
+                quote = null;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            current += char;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (current) {
+                tokens.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += char;
+    }
+    if (current) {
+        tokens.push(current);
+    }
+    return tokens;
+}
+function renderAttrList(style) {
+    const attrs = { ...(style.attrs ?? {}) };
+    const effectiveLayout = inferEffectiveImageLayout(style);
+    if (effectiveLayout && !Object.hasOwn(attrs, "data-layout")) {
+        attrs["data-layout"] = effectiveLayout;
+    }
+    if (style.align && !Object.hasOwn(attrs, "data-align")) {
+        attrs["data-align"] = style.align;
+    }
+    if (style.width && !Object.hasOwn(attrs, "width")) {
+        attrs.width = style.width;
+    }
+    if (style.height && !Object.hasOwn(attrs, "height")) {
+        attrs.height = style.height;
+    }
+    const tokens = [];
+    if (style.id) {
+        tokens.push(`#${style.id}`);
+    }
+    for (const className of style.classes ?? []) {
+        if (className.trim().length > 0) {
+            tokens.push(`.${className.trim()}`);
+        }
+    }
+    if (Object.hasOwn(attrs, "width")) {
+        tokens.push(`width=${formatAttrValue(attrs.width)}`);
+        delete attrs.width;
+    }
+    if (Object.hasOwn(attrs, "height")) {
+        tokens.push(`height=${formatAttrValue(attrs.height)}`);
+        delete attrs.height;
+    }
+    const remainingKeys = Object.keys(attrs).sort((a, b) => a.localeCompare(b));
+    for (const key of remainingKeys) {
+        tokens.push(`${key}=${formatAttrValue(attrs[key])}`);
+    }
+    if (tokens.length === 0) {
+        return "";
+    }
+    return `{${tokens.join(" ")}}`;
+}
+function formatAttrValue(value) {
+    const normalized = value.trim();
+    if (/^[A-Za-z0-9._%:/+-]+$/.test(normalized)) {
+        return normalized;
+    }
+    return `"${normalized.replaceAll('"', '\\"')}"`;
+}
+function applyImageStyleField(style, key, value, metadataPath, warnings) {
+    if (key === "width" || key === "height" || key === "id") {
+        if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+            warnings.push(`Metadata '${metadataPath}' must be a scalar value.`);
+            return;
+        }
+        const normalized = normalizeImageScalar(value);
+        if (!normalized) {
+            return;
+        }
+        if (key === "width") {
+            style.width = normalized;
+        }
+        else if (key === "height") {
+            style.height = normalized;
+        }
+        else {
+            style.id = normalized;
+        }
+        return;
+    }
+    if (key === "classes") {
+        const classes = normalizeImageClasses(value);
+        if (!classes) {
+            warnings.push(`Metadata '${metadataPath}' must be a string or array of strings.`);
+            return;
+        }
+        if (classes && classes.length > 0) {
+            style.classes = classes;
+        }
+        return;
+    }
+    if (key === "attrs") {
+        const attrsRecord = asPlainRecord(value);
+        if (!attrsRecord) {
+            warnings.push(`Metadata '${metadataPath}' must be an object of scalar values.`);
+            return;
+        }
+        for (const [attrKey, attrValue] of Object.entries(attrsRecord)) {
+            if (typeof attrValue !== "string" && typeof attrValue !== "number" && typeof attrValue !== "boolean") {
+                warnings.push(`Metadata '${metadataPath}.${attrKey}' must be a scalar value.`);
+            }
+        }
+        const attrs = normalizeImageAttrs(attrsRecord);
+        if (attrs && Object.keys(attrs).length > 0) {
+            style.attrs = attrs;
+        }
+        return;
+    }
+    if (key === "layout") {
+        if (value !== "block" && value !== "inline") {
+            warnings.push(`Metadata '${metadataPath}' must be either 'block' or 'inline'.`);
+            return;
+        }
+        style.layout = value;
+        return;
+    }
+    if (key === "align") {
+        if (value !== "left" && value !== "center" && value !== "right") {
+            warnings.push(`Metadata '${metadataPath}' must be one of: left, center, right.`);
+            return;
+        }
+        style.align = value;
+        return;
+    }
+    warnings.push(`Unsupported image style key '${key}' in '${metadataPath}'. Allowed keys: width, height, classes, id, attrs, layout, align.`);
+}
+function stripWrappingQuotes(value) {
+    if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function isPathInside(candidatePath, parentPath) {
+    const relative = path.relative(path.resolve(parentPath), path.resolve(candidatePath));
+    if (!relative) {
+        return true;
+    }
+    return !relative.startsWith("..") && !path.isAbsolute(relative);
+}

package/dist/stego-cli/src/modules/export/application/run-export.js

@@ -18,12 +18,33 @@ export function runExport(input) {
     if (!capability.ok) {
         throw new Error(capability.reason || `Exporter '${exporter.id}' cannot run.`);
     }
+    const resourcePaths = uniqueResolvedPaths([
+        input.project.root,
+        input.project.manuscriptDir,
+        path.join(input.project.root, "assets"),
+        path.dirname(input.inputPath)
+    ]);
     exporter.run({
         inputPath: input.inputPath,
-        outputPath
+        outputPath,
+        cwd: input.project.root,
+        resourcePaths
     });
     return {
         outputPath,
         format
     };
 }
+function uniqueResolvedPaths(paths) {
+    const seen = new Set();
+    const unique = [];
+    for (const value of paths) {
+        const normalized = path.resolve(value);
+        if (seen.has(normalized)) {
+            continue;
+        }
+        seen.add(normalized);
+        unique.push(normalized);
+    }
+    return unique;
+}

package/dist/stego-cli/src/modules/export/commands/export.js

@@ -8,9 +8,8 @@ export function registerExportCommand(registry) {
     registry.register({
         name: "export",
         description: "Export manuscript formats",
-        allowUnknownOptions: true,
         options: [
-            { flags: "--project <project-id>", description: "Project id" },
+            { flags: "-p, --project <project-id>", description: "Project id" },
             { flags: "--format <format>", description: "md|docx|pdf|epub" },
             { flags: "--output <path>", description: "Explicit output path" },
             { flags: "--root <path>", description: "Workspace root path" }

package/dist/stego-cli/src/modules/export/infra/pandoc-exporter.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 function hasPandoc() {
     const result = spawnSync("pandoc", ["--version"], { stdio: "ignore" });
     return result.status === 0;
@@ -21,6 +22,20 @@ function resolvePdfEngine() {
 function getMissingPdfEngineReason() {
     return "No PDF engine found. Install one of: tectonic, xelatex, lualatex, pdflatex, wkhtmltopdf, weasyprint, prince, or typst.";
 }
+function resolveBundledFile(relativePathFromPackageRoot) {
+    let current = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        const candidate = path.join(current, relativePathFromPackageRoot);
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+}
 export function createPandocExporter(format) {
     return {
         id: format,
@@ -40,9 +55,20 @@ export function createPandocExporter(format) {
             }
             return { ok: true };
         },
-        run({ inputPath, outputPath }) {
+        run({ inputPath, outputPath, cwd, resourcePaths }) {
             fs.mkdirSync(path.dirname(outputPath), { recursive: true });
             const args = [inputPath, "-o", outputPath];
+            const imageLayoutFilter = resolveBundledFile(path.join("filters", "image-layout.lua"));
+            if (imageLayoutFilter) {
+                args.push("--lua-filter", imageLayoutFilter);
+            }
+            const imageLayoutStylesheet = resolveBundledFile(path.join("filters", "image-layout.css"));
+            if (format === "epub" && imageLayoutStylesheet) {
+                args.push("--css", imageLayoutStylesheet);
+            }
+            if (resourcePaths && resourcePaths.length > 0) {
+                args.push(`--resource-path=${resourcePaths.join(path.delimiter)}`);
+            }
             if (format === "pdf") {
                 const engine = resolvePdfEngine();
                 if (!engine) {
@@ -51,7 +77,8 @@ export function createPandocExporter(format) {
                 args.push(`--pdf-engine=${engine}`);
             }
             const result = spawnSync("pandoc", args, {
-                encoding: "utf8"
+                encoding: "utf8",
+                cwd: cwd || undefined
             });
             if (result.status !== 0) {
                 const stderr = (result.stderr || "").trim();

package/dist/stego-cli/src/modules/manuscript/commands/new-manuscript.js

@@ -7,7 +7,7 @@ export function registerNewManuscriptCommand(registry) {
         name: "new",
         description: "Create a new manuscript file",
         options: [
-            { flags: "--project <project-id>", description: "Project id" },
+            { flags: "-p, --project <project-id>", description: "Project id" },
             { flags: "-i, --i <prefix>", description: "Numeric filename prefix override" },
             { flags: "--filename <name>", description: "Explicit manuscript filename" },
             { flags: "--format <format>", description: "text|json" },

package/dist/stego-cli/src/modules/project/application/create-project.js

@@ -22,7 +22,7 @@ const PROSE_MARKDOWN_EDITOR_SETTINGS = {
 export function createProject(input) {
     const projectId = (input.projectId || "").trim();
     if (!projectId) {
-        throw new CliError("INVALID_USAGE", "Project id is required. Use --project <project-id>.");
+        throw new CliError("INVALID_USAGE", "Project id is required. Use --project/-p <project-id>.");
     }
     if (!isValidProjectId(projectId)) {
         throw new CliError("INVALID_USAGE", "Project id must match /^[a-z0-9][a-z0-9-]*$/.");
@@ -34,10 +34,12 @@ export function createProject(input) {
     const manuscriptDir = path.join(projectRoot, input.workspace.config.chapterDir);
     const spineDir = path.join(projectRoot, input.workspace.config.spineDir);
     const notesDir = path.join(projectRoot, input.workspace.config.notesDir);
+    const assetsDir = path.join(projectRoot, "assets");
     const distDir = path.join(projectRoot, input.workspace.config.distDir);
     ensureDirectory(manuscriptDir);
     ensureDirectory(spineDir);
     ensureDirectory(notesDir);
+    ensureDirectory(assetsDir);
     ensureDirectory(distDir);
     const projectJsonPath = path.join(projectRoot, "stego-project.json");
     writeTextFile(projectJsonPath, `${JSON.stringify({
@@ -95,6 +97,43 @@ label: Characters
 `);
     const charactersEntryPath = path.join(charactersDir, "example-character.md");
     writeTextFile(charactersEntryPath, "# Example Character\n\n");
+    const assetsReadmePath = path.join(assetsDir, "README.md");
+    writeTextFile(assetsReadmePath, `# Assets
+
+Store manuscript images in this directory (or subdirectories).
+
+Use standard Markdown image syntax in manuscript files, typically with paths like:
+
+\`\`\`md
+![Map](../assets/maps/city-plan.png)
+\`\`\`
+
+Optional manuscript frontmatter image settings:
+
+\`\`\`json
+// stego-project.json
+{
+  "images": {
+    "layout": "block",
+    "align": "center",
+    "width": "50%"
+  }
+}
+\`\`\`
+
+\`\`\`yaml
+# manuscript frontmatter overrides
+images:
+  assets/maps/city-plan.png:
+    layout: inline
+    align: left
+    width: 100%
+\`\`\`
+
+Manuscript frontmatter \`images\` is for per-path overrides.
+Global defaults belong in \`stego-project.json\` under \`images\`.
+
+`);
     const projectExtensionsPath = ensureProjectExtensionsRecommendations(projectRoot);
     let projectSettingsPath;
     if (input.enableProseFont) {
@@ -109,6 +148,7 @@ label: Characters
             path.relative(input.workspace.repoRoot, starterManuscriptPath),
             path.relative(input.workspace.repoRoot, charactersCategoryPath),
             path.relative(input.workspace.repoRoot, charactersEntryPath),
+            path.relative(input.workspace.repoRoot, assetsReadmePath),
             path.relative(input.workspace.repoRoot, projectExtensionsPath),
             ...(projectSettingsPath ? [path.relative(input.workspace.repoRoot, projectSettingsPath)] : [])
         ]

package/dist/stego-cli/src/modules/project/application/infer-project.js

@@ -6,7 +6,7 @@ export function resolveProjectContext(input) {
     const projectIds = listProjectIds(input.workspace);
     const projectId = resolveProjectIdCandidate(input, projectIds);
     if (!projectId) {
-        throw new CliError("PROJECT_NOT_FOUND", "Project id is required. Use --project <project-id>.");
+        throw new CliError("PROJECT_NOT_FOUND", "Project id is required. Use --project/-p <project-id>.");
     }
     const projectRoot = path.join(input.workspace.repoRoot, input.workspace.config.projectsDir, projectId);
     const projectJsonPath = path.join(projectRoot, "stego-project.json");

package/dist/stego-cli/src/modules/project/commands/new-project.js

@@ -8,7 +8,7 @@ export function registerNewProjectCommand(registry) {
         name: "new-project",
         description: "Create a new Stego project",
         options: [
-            { flags: "--project <project-id>", description: "Project id" },
+            { flags: "-p, --project <project-id>", description: "Project id" },
             { flags: "--title <title>", description: "Project title" },
             { flags: "--prose-font <mode>", description: "yes|no|prompt" },
             { flags: "--format <format>", description: "text|json" },