stego-cli 0.4.2 → 0.5.0

package/README.md

@@ -17,9 +17,9 @@ stego init
 npm install
 
 stego list-projects
-stego validate --project fiction-example
-stego build --project fiction-example
-stego new --project fiction-example
+stego validate -p fiction-example
+stego build -p fiction-example
+stego new -p fiction-example
 ```
 
 `stego init` scaffolds two example projects:
@@ -54,18 +54,20 @@ Run commands from the workspace root and target a project with `--project`.
 
 ```bash
 stego list-projects
-stego new-project --project my-book --title "My Book"
-stego new --project fiction-example
-stego validate --project fiction-example
-stego build --project fiction-example
-stego check-stage --project fiction-example --stage revise
-stego export --project fiction-example --format md
-stego spine read --project fiction-example
-stego spine new-category --project fiction-example --key characters
-stego spine new --project fiction-example --category characters --filename supporting/abigail
+stego new-project -p my-book --title "My Book"
+stego new -p fiction-example
+stego validate -p fiction-example
+stego build -p fiction-example
+stego check-stage -p fiction-example --stage revise
+stego export -p fiction-example --format md
+stego spine read -p fiction-example
+stego spine new-category -p fiction-example --key characters
+stego spine new -p fiction-example --category characters --filename supporting/abigail
 stego metadata read projects/fiction-example/manuscript/100-the-commission.md --format json
 ```
 
+All project-scoped commands accept `-p` as shorthand for `--project`.
+
 `stego new` also supports `--i <prefix>` for numeric prefix override and `--filename <name>` for an explicit manuscript filename.
 
 Spine V2 is directory-inferred:
@@ -74,6 +76,50 @@ Spine V2 is directory-inferred:
 - category metadata lives at `spine/<category>/_category.md`
 - entries are markdown files in each category directory tree
 
+## Image assets and manuscript image settings
+
+Stego projects scaffold an `assets/` directory for manuscript images.
+
+Use standard Markdown image syntax in manuscript files:
+
+```md
+![Map](../assets/maps/city-plan.png)
+```
+
+Set global image defaults in `stego-project.json`:
+
+```json
+{
+  "images": {
+    "layout": "block",
+    "align": "center",
+    "width": "50%",
+    "classes": ["illustration"]
+  }
+}
+```
+
+Use manuscript frontmatter `images` only for per-path overrides:
+
+```yaml
+images:
+  assets/maps/city-plan.png:
+    layout: inline
+    align: left
+    width: 100%
+    classes: [diagram]
+```
+
+Rules:
+
+- project-level global keys in `stego-project.json images`: `width`, `height`, `classes`, `id`, `attrs`, `layout`, `align`
+- manuscript frontmatter `images` keys are per-image overrides by project-relative asset path
+- manuscript frontmatter should not define global keys; put defaults in `stego-project.json`
+- `layout` (`block|inline`) and `align` (`left|center|right`) are emitted as image attrs (`data-layout`, `data-align`) in compiled markdown
+- EPUB export includes a default image layout stylesheet (`filters/image-layout.css`) for `data-layout`/`data-align` behavior
+- inline image attrs in markdown win over both project defaults and frontmatter overrides
+- local manuscript image targets outside `assets/` are reported as validate warnings
+
 Projects also include local npm scripts so you can work from inside a project directory.
 
 ## Complete CLI command reference
@@ -90,16 +136,16 @@ Current `stego --help` command index:
 ```text
 init [--force]
 list-projects [--root <path>]
-new-project --project <project-id> [--title <title>] [--prose-font <yes|no|prompt>] [--format <text|json>] [--root <path>]
-new --project <project-id> [--i <prefix>|-i <prefix>] [--filename <name>] [--format <text|json>] [--root <path>]
-validate --project <project-id> [--file <project-relative-manuscript-path>] [--root <path>]
-build --project <project-id> [--root <path>]
-check-stage --project <project-id> --stage <draft|revise|line-edit|proof|final> [--file <project-relative-manuscript-path>] [--root <path>]
-lint --project <project-id> [--manuscript|--spine] [--root <path>]
-export --project <project-id> --format <md|docx|pdf|epub> [--output <path>] [--root <path>]
-spine read --project <project-id> [--format <text|json>] [--root <path>]
-spine new-category --project <project-id> --key <category> [--label <label>] [--require-metadata] [--format <text|json>] [--root <path>]
-spine new --project <project-id> --category <category> [--filename <relative-path>] [--format <text|json>] [--root <path>]
+new-project --project|-p <project-id> [--title <title>] [--prose-font <yes|no|prompt>] [--format <text|json>] [--root <path>]
+new --project|-p <project-id> [--i <prefix>|-i <prefix>] [--filename <name>] [--format <text|json>] [--root <path>]
+validate --project|-p <project-id> [--file <project-relative-manuscript-path>] [--root <path>]
+build --project|-p <project-id> [--root <path>]
+check-stage --project|-p <project-id> --stage <draft|revise|line-edit|proof|final> [--file <project-relative-manuscript-path>] [--root <path>]
+lint --project|-p <project-id> [--manuscript|--spine] [--root <path>]
+export --project|-p <project-id> --format <md|docx|pdf|epub> [--output <path>] [--root <path>]
+spine read --project|-p <project-id> [--format <text|json>] [--root <path>]
+spine new-category --project|-p <project-id> --key <category> [--label <label>] [--require-metadata] [--format <text|json>] [--root <path>]
+spine new --project|-p <project-id> --category <category> [--filename <relative-path>] [--format <text|json>] [--root <path>]
 metadata read <markdown-path> [--format <text|json>]
 metadata apply <markdown-path> --input <path|-> [--format <text|json>]
 comments read <manuscript> [--format <text|json>]

package/dist/shared/src/domain/frontmatter/validators.js

@@ -32,7 +32,18 @@ export function normalizeFrontmatterRecord(raw) {
 }
 function normalizeFrontmatterValue(value, key) {
     if (Array.isArray(value)) {
-        return value.map((item) => normalizeFrontmatterScalar(item, key));
+        return value.map((item) => normalizeFrontmatterValue(item, key));
+    }
+    if (isPlainObject(value)) {
+        const result = {};
+        for (const [entryKey, entryValue] of Object.entries(value)) {
+            const normalizedKey = entryKey.trim();
+            if (!normalizedKey) {
+                throw new Error(`Metadata key '${key}' contains an empty nested key.`);
+            }
+            result[normalizedKey] = normalizeFrontmatterValue(entryValue, key);
+        }
+        return result;
     }
     return normalizeFrontmatterScalar(value, key);
 }
@@ -43,5 +54,12 @@ function normalizeFrontmatterScalar(value, key) {
     if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
         return value;
     }
-    throw new Error(`Metadata key '${key}' must be a scalar or array of scalars.`);
+    throw new Error(`Metadata key '${key}' must be scalar, array, or object.`);
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
 }

package/dist/shared/src/domain/images/index.js

@@ -0,0 +1 @@
+export * from "./style.js";

package/dist/shared/src/domain/images/style.js

@@ -0,0 +1,185 @@
+export const IMAGE_STYLE_KEYS = ["width", "height", "classes", "id", "attrs", "layout", "align"];
+export const IMAGE_GLOBAL_KEYS = new Set(IMAGE_STYLE_KEYS);
+export function asPlainRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        return undefined;
+    }
+    return value;
+}
+export function normalizeImageScalar(value) {
+    if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+        return undefined;
+    }
+    const normalized = String(value).trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+export function normalizeImageClasses(value) {
+    if (typeof value === "string") {
+        const classes = value
+            .split(/\s+/)
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0);
+        return classes;
+    }
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const classes = [];
+    for (const entry of value) {
+        if (typeof entry !== "string") {
+            return undefined;
+        }
+        const normalized = entry.trim();
+        if (!normalized) {
+            continue;
+        }
+        classes.push(normalized);
+    }
+    return classes;
+}
+export function normalizeImageAttrs(value) {
+    const record = asPlainRecord(value);
+    if (!record) {
+        return undefined;
+    }
+    const attrs = {};
+    for (const [key, raw] of Object.entries(record)) {
+        const normalized = normalizeImageScalar(raw);
+        if (!normalized) {
+            continue;
+        }
+        attrs[key] = normalized;
+    }
+    return Object.keys(attrs).length > 0 ? attrs : undefined;
+}
+export function cloneImageStyle(style) {
+    return {
+        width: style?.width,
+        height: style?.height,
+        id: style?.id,
+        classes: style?.classes ? [...style.classes] : undefined,
+        attrs: style?.attrs ? { ...style.attrs } : undefined,
+        layout: style?.layout,
+        align: style?.align
+    };
+}
+export function mergeImageStyles(base, override) {
+    const merged = cloneImageStyle(base);
+    if (override.width) {
+        merged.width = override.width;
+    }
+    if (override.height) {
+        merged.height = override.height;
+    }
+    if (override.id) {
+        merged.id = override.id;
+    }
+    if (override.layout) {
+        merged.layout = override.layout;
+    }
+    if (override.align) {
+        merged.align = override.align;
+    }
+    if (override.classes && override.classes.length > 0) {
+        merged.classes = [...override.classes];
+    }
+    const attrs = { ...(merged.attrs ?? {}) };
+    for (const [key, value] of Object.entries(override.attrs ?? {})) {
+        attrs[key] = value;
+    }
+    merged.attrs = Object.keys(attrs).length > 0 ? attrs : undefined;
+    return merged;
+}
+export function isImageStyleEmpty(style) {
+    if (!style) {
+        return true;
+    }
+    return !style.width
+        && !style.height
+        && !style.id
+        && !style.layout
+        && !style.align
+        && (!style.classes || style.classes.length === 0)
+        && (!style.attrs || Object.keys(style.attrs).length === 0);
+}
+export function parseImageStyle(value) {
+    const record = asPlainRecord(value);
+    if (!record) {
+        return undefined;
+    }
+    const style = {};
+    for (const [key, raw] of Object.entries(record)) {
+        if (key === "width" || key === "height" || key === "id") {
+            const normalized = normalizeImageScalar(raw);
+            if (normalized) {
+                style[key] = normalized;
+            }
+            continue;
+        }
+        if (key === "layout") {
+            if (raw === "block" || raw === "inline") {
+                style.layout = raw;
+            }
+            continue;
+        }
+        if (key === "align") {
+            if (raw === "left" || raw === "center" || raw === "right") {
+                style.align = raw;
+            }
+            continue;
+        }
+        if (key === "classes") {
+            const normalized = normalizeImageClasses(raw);
+            if (normalized) {
+                style.classes = normalized;
+            }
+            continue;
+        }
+        if (key === "attrs") {
+            const normalized = normalizeImageAttrs(raw);
+            if (normalized) {
+                style.attrs = normalized;
+            }
+            continue;
+        }
+    }
+    const layoutFromAttrs = style.attrs?.["data-layout"];
+    if (!style.layout && (layoutFromAttrs === "block" || layoutFromAttrs === "inline")) {
+        style.layout = layoutFromAttrs;
+    }
+    const alignFromAttrs = style.attrs?.["data-align"];
+    if (!style.align && (alignFromAttrs === "left" || alignFromAttrs === "center" || alignFromAttrs === "right")) {
+        style.align = alignFromAttrs;
+    }
+    return isImageStyleEmpty(style) ? undefined : style;
+}
+export function normalizeImagePathKey(value) {
+    return value.trim().replaceAll("\\", "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+export function extractImageDestinationTarget(value) {
+    let target = value.trim();
+    if (target.startsWith("<") && target.endsWith(">")) {
+        target = target.slice(1, -1).trim();
+    }
+    return target
+        .split(/\s+"/)[0]
+        .split(/\s+'/)[0]
+        .trim();
+}
+export function stripImageQueryAndAnchor(target) {
+    return target.split("#")[0].split("?")[0].trim();
+}
+export function isExternalImageTarget(target) {
+    return target.startsWith("http://")
+        || target.startsWith("https://")
+        || target.startsWith("mailto:")
+        || target.startsWith("tel:")
+        || target.startsWith("data:");
+}
+export function inferEffectiveImageLayout(style) {
+    return style.layout ?? (style.align ? "block" : undefined);
+}

package/dist/shared/src/index.js

@@ -3,4 +3,5 @@ export * as FrontmatterDomain from "./domain/frontmatter/index.js";
 export * as CommentsDomain from "./domain/comments/index.js";
 export * as StagesDomain from "./domain/stages/index.js";
 export * as ProjectDomain from "./domain/project/index.js";
+export * as ImagesDomain from "./domain/images/index.js";
 export * as SharedUtils from "./utils/index.js";

package/dist/stego-cli/src/app/command-registry.js

@@ -3,15 +3,62 @@ export class CommandRegistry {
     cli;
     appContext;
     multiTokenCommandMappings = [];
+    helpEntries = [];
     constructor(appContext) {
         this.appContext = appContext;
         this.cli = cac("stego");
     }
     showHelp() {
-        this.cli.outputHelp();
+        const commandWidth = this.helpEntries.reduce((max, entry) => Math.max(max, entry.usageName.length), 0);
+        const lines = [
+            "stego",
+            "",
+            "Usage:",
+            "  $ stego <command> [options]",
+            "",
+            "Commands:"
+        ];
+        for (const entry of this.helpEntries) {
+            lines.push(`  ${entry.usageName.padEnd(commandWidth + 2)}${entry.description}`);
+        }
+        lines.push("");
+        lines.push("For more info, run any command with the `--help` flag:");
+        for (const entry of this.helpEntries) {
+            lines.push(`  $ stego ${entry.commandTokens.join(" ")} --help`);
+        }
+        this.appContext.stdout.write(`${lines.join("\n")}\n`);
+    }
+    tryShowCommandHelp(argv) {
+        if (!containsHelpFlag(argv)) {
+            return false;
+        }
+        const candidate = argv.filter((token) => token !== "--help" && token !== "-h");
+        const entry = this.findHelpEntry(candidate);
+        if (!entry) {
+            return false;
+        }
+        const optionRows = [...entry.options.map((option) => ({
+                flags: option.flags,
+                description: option.description ?? ""
+            })), { flags: "-h, --help", description: "Display this message" }];
+        const optionWidth = optionRows.reduce((max, row) => Math.max(max, row.flags.length), 0);
+        const lines = [
+            "stego",
+            "",
+            "Usage:",
+            `  $ stego ${entry.usageName}`,
+            "",
+            "Options:"
+        ];
+        for (const row of optionRows) {
+            lines.push(`  ${row.flags.padEnd(optionWidth + 2)}${row.description}`);
+        }
+        this.appContext.stdout.write(`${lines.join("\n")}\n`);
+        return true;
     }
     register(spec) {
         const commandName = normalizeRegisteredCommandName(spec.name, this.multiTokenCommandMappings);
+        this.helpEntries.push(createCommandHelpEntry(spec.name, spec.description, spec.options ?? []));
         let command = this.cli.command(commandName, spec.description);
         for (const option of spec.options ?? []) {
             const optionConfig = option.defaultValue === undefined
@@ -46,6 +93,27 @@ export class CommandRegistry {
         }
         return this.cli.runMatchedCommand();
     }
+    findHelpEntry(argv) {
+        if (argv.length === 0) {
+            return null;
+        }
+        const entries = [...this.helpEntries]
+            .sort((a, b) => b.commandTokens.length - a.commandTokens.length);
+        for (const entry of entries) {
+            if (startsWithTokens(argv, entry.commandTokens)) {
+                return entry;
+            }
+        }
+        const colonCandidate = argv[0];
+        if (typeof colonCandidate === "string") {
+            for (const entry of entries) {
+                if (entry.normalizedToken === colonCandidate) {
+                    return entry;
+                }
+            }
+        }
+        return null;
+    }
 }
 function normalizeRegisteredCommandName(rawName, mappings) {
     const tokens = rawName.trim().split(/\s+/).filter(Boolean);
@@ -72,6 +140,27 @@ function normalizeRegisteredCommandName(rawName, mappings) {
         ? `${normalizedToken} ${argumentTokens.join(" ")}`
         : normalizedToken;
 }
+function createCommandHelpEntry(rawName, description, options) {
+    const tokens = rawName.trim().split(/\s+/).filter(Boolean);
+    const commandTokens = extractCommandTokens(tokens);
+    return {
+        usageName: rawName,
+        description,
+        commandTokens,
+        normalizedToken: commandTokens.join(":"),
+        options
+    };
+}
+function extractCommandTokens(tokens) {
+    const commandTokens = [];
+    for (const token of tokens) {
+        if (token.startsWith("<") || token.startsWith("[")) {
+            break;
+        }
+        commandTokens.push(token);
+    }
+    return commandTokens;
+}
 function normalizeIncomingArgv(argv, mappings) {
     if (argv.length === 0 || mappings.length === 0) {
         return argv;
@@ -100,6 +189,9 @@ function normalizeDashInputValueArgv(argv) {
     }
     return normalized;
 }
+function containsHelpFlag(argv) {
+    return argv.includes("--help") || argv.includes("-h");
+}
 function startsWithTokens(input, expected) {
     if (input.length < expected.length) {
         return false;

package/dist/stego-cli/src/app/create-cli-app.js

@@ -19,6 +19,9 @@ export function createCliApp(appContext) {
                 writeText(resolveCliVersion());
                 return;
             }
+            if (registry.tryShowCommandHelp(appContext.argv)) {
+                return;
+            }
             try {
                 await registry.run(appContext.argv);
             }

package/dist/stego-cli/src/app/error-boundary.js

@@ -1,5 +1,15 @@
 function shouldRenderJsonError(argv) {
-    return argv.includes("--format") && argv.includes("json");
+    for (let index = 0; index < argv.length; index += 1) {
+        const current = argv[index];
+        const next = argv[index + 1];
+        if (current === "--format" && typeof next === "string" && next.toLowerCase() === "json") {
+            return true;
+        }
+        if (current.startsWith("--format=") && current.slice("--format=".length).toLowerCase() === "json") {
+            return true;
+        }
+    }
+    return false;
 }
 function errorEnvelope(code, message, details) {
     return {

package/dist/stego-cli/src/modules/comments/commands/comments-add.js

@@ -6,7 +6,6 @@ export function registerCommentsAddCommand(registry) {
     registry.register({
         name: "comments add <manuscript>",
         description: "Add a new comment",
-        allowUnknownOptions: true,
         options: [
             { flags: "--message <text>", description: "Comment text" },
             { flags: "--author <name>", description: "Comment author" },

package/dist/stego-cli/src/modules/comments/commands/comments-clear-resolved.js

@@ -6,7 +6,6 @@ export function registerCommentsClearResolvedCommand(registry) {
     registry.register({
         name: "comments clear-resolved <manuscript>",
         description: "Clear resolved comments",
-        allowUnknownOptions: true,
         options: [
             { flags: "--format <format>", description: "text|json" }
         ],

package/dist/stego-cli/src/modules/comments/commands/comments-delete.js

@@ -6,7 +6,6 @@ export function registerCommentsDeleteCommand(registry) {
     registry.register({
         name: "comments delete <manuscript>",
         description: "Delete a comment",
-        allowUnknownOptions: true,
         options: [
             { flags: "--comment-id <id>", description: "Comment id (CMT-####)" },
             { flags: "--format <format>", description: "text|json" }

package/dist/stego-cli/src/modules/comments/commands/comments-read.js

@@ -6,7 +6,6 @@ export function registerCommentsReadCommand(registry) {
     registry.register({
         name: "comments read <manuscript>",
         description: "Read comments state",
-        allowUnknownOptions: true,
         options: [
             { flags: "--format <format>", description: "text|json" }
         ],

package/dist/stego-cli/src/modules/comments/commands/comments-reply.js

@@ -6,7 +6,6 @@ export function registerCommentsReplyCommand(registry) {
     registry.register({
         name: "comments reply <manuscript>",
         description: "Reply to an existing comment",
-        allowUnknownOptions: true,
         options: [
             { flags: "--comment-id <id>", description: "Comment id (CMT-####)" },
             { flags: "--message <text>", description: "Reply text" },

package/dist/stego-cli/src/modules/comments/commands/comments-set-status.js

@@ -6,7 +6,6 @@ export function registerCommentsSetStatusCommand(registry) {
     registry.register({
         name: "comments set-status <manuscript>",
         description: "Set comment status",
-        allowUnknownOptions: true,
         options: [
             { flags: "--comment-id <id>", description: "Comment id (CMT-####)" },
             { flags: "--status <status>", description: "open|resolved" },

package/dist/stego-cli/src/modules/comments/commands/comments-sync-anchors.js

@@ -6,7 +6,6 @@ export function registerCommentsSyncAnchorsCommand(registry) {
     registry.register({
         name: "comments sync-anchors <manuscript>",
         description: "Sync comment anchors",
-        allowUnknownOptions: true,
         options: [
             { flags: "--input <path>", description: "JSON payload path or '-'" },
             { flags: "--format <format>", description: "text|json" }

package/dist/stego-cli/src/modules/compile/application/compile-manuscript.js

@@ -1,14 +1,25 @@
 import { nowIsoString } from "../../../platform/clock.js";
 import { renderCompiledManuscript } from "../domain/compile-structure.js";
+import { rewriteMarkdownImagesForChapter } from "../domain/image-settings.js";
 import { writeCompiledOutput } from "../infra/dist-writer.js";
 export function compileManuscript(input) {
+    const chapters = input.chapters.map((chapter) => ({
+        ...chapter,
+        body: rewriteMarkdownImagesForChapter({
+            body: chapter.body,
+            chapterPath: chapter.path,
+            projectRoot: input.project.root,
+            projectMeta: input.project.meta,
+            frontmatter: chapter.metadata
+        })
+    }));
     const markdown = renderCompiledManuscript({
         generatedAt: nowIsoString(),
         projectId: input.project.id,
         title: input.project.meta.title || input.project.id,
         subtitle: input.project.meta.subtitle,
         author: input.project.meta.author,
-        chapters: input.chapters,
+        chapters,
         compileStructureLevels: input.compileStructureLevels
     });
     const outputPath = writeCompiledOutput(input.project.distDir, input.project.id, markdown);

package/dist/stego-cli/src/modules/compile/commands/build.js

@@ -7,9 +7,8 @@ export function registerBuildCommand(registry) {
     registry.register({
         name: "build",
         description: "Compile manuscript output",
-        allowUnknownOptions: true,
         options: [
-            { flags: "--project <project-id>", description: "Project id" },
+            { flags: "-p, --project <project-id>", description: "Project id" },
             { flags: "--root <path>", description: "Workspace root path" }
         ],
         action: (context) => {

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

@@ -2,7 +2,6 @@ export function renderCompiledManuscript(input) {
     const tocEntries = [];
     const previousGroupValues = new Map();
     const previousGroupTitles = new Map();
-    const entryHeadingLevel = Math.min(6, 2 + input.compileStructureLevels.length);
     const lines = [];
     lines.push(`<!-- generated: ${input.generatedAt} -->`);
     lines.push("");
@@ -59,8 +58,6 @@ export function renderCompiledManuscript(input) {
             previousGroupValues.set(level.key, currentValue);
             previousGroupTitles.set(level.key, currentTitle);
         }
-        lines.push(`${"#".repeat(entryHeadingLevel)} ${chapter.title}`);
-        lines.push("");
         lines.push(`<!-- source: ${chapter.relativePath} | order: ${chapter.order} | status: ${chapter.status} -->`);
         lines.push("");
         lines.push(chapter.body.trim());