stego-cli 0.4.0 → 0.4.2

package/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "matt-gold.stego-extension",
+    "matt-gold.saurus-extension",
+    "streetsidesoftware.code-spell-checker"
+  ]
+}

package/README.md

@@ -42,6 +42,12 @@ Start by reading the manuscript files in order, or build the docs project:
 stego build --project stego-docs
 ```
 
+## Architecture
+
+Internal architecture notes for the domain-first module layout live in:
+
+- `docs/architecture.md`
+
 ## Core commands
 
 Run commands from the workspace root and target a project with `--project`.
@@ -70,6 +76,41 @@ Spine V2 is directory-inferred:
 
 Projects also include local npm scripts so you can work from inside a project directory.
 
+## Complete CLI command reference
+
+The full command surface is available via:
+
+```bash
+stego --help
+stego --version
+```
+
+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>]
+metadata read <markdown-path> [--format <text|json>]
+metadata apply <markdown-path> --input <path|-> [--format <text|json>]
+comments read <manuscript> [--format <text|json>]
+comments add <manuscript> [--message <text> | --input <path|->] [--author <name>] [--start-line <n> --start-col <n> --end-line <n> --end-col <n>] [--cursor-line <n>] [--format <text|json>]
+comments reply <manuscript> --comment-id <CMT-####> [--message <text> | --input <path|->] [--author <name>] [--format <text|json>]
+comments set-status <manuscript> --comment-id <CMT-####> --status <open|resolved> [--thread] [--format <text|json>]
+comments delete <manuscript> --comment-id <CMT-####> [--format <text|json>]
+comments clear-resolved <manuscript> [--format <text|json>]
+comments sync-anchors <manuscript> --input <path|-> [--format <text|json>]
+```
+
 ## Advanced integration command
 
 `stego comments add` is a machine-facing command for editor/tool integrations.

package/dist/shared/src/contracts/cli/envelopes.js

@@ -0,0 +1,19 @@
+export const CLI_CONTRACT_VERSION = 1;
+export function successEnvelope(operation, data) {
+    return {
+        ok: true,
+        version: CLI_CONTRACT_VERSION,
+        operation,
+        data
+    };
+}
+export function errorEnvelope(code, message, options) {
+    return {
+        ok: false,
+        version: CLI_CONTRACT_VERSION,
+        operation: options?.operation,
+        code,
+        message,
+        details: options?.details
+    };
+}

package/dist/shared/src/contracts/cli/errors.js

@@ -0,0 +1,14 @@
+import { getExitCodeForError } from "./exit-codes.js";
+export class CliError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "CliError";
+        this.code = code;
+        this.details = details;
+    }
+    get exitCode() {
+        return getExitCodeForError(this.code);
+    }
+}

package/dist/shared/src/contracts/cli/exit-codes.js

@@ -0,0 +1,15 @@
+const EXIT_CODES = {
+    INVALID_USAGE: 2,
+    WORKSPACE_NOT_FOUND: 3,
+    PROJECT_NOT_FOUND: 3,
+    INVALID_CONFIGURATION: 4,
+    INVALID_PAYLOAD: 4,
+    VALIDATION_FAILED: 5,
+    COMMENT_APPENDIX_INVALID: 5,
+    WRITE_FAILURE: 6,
+    TOOLING_MISSING: 7,
+    INTERNAL_ERROR: 1
+};
+export function getExitCodeForError(code) {
+    return EXIT_CODES[code] ?? 1;
+}

package/dist/shared/src/contracts/cli/index.js

@@ -0,0 +1,6 @@
+export * from "./operations.js";
+export * from "./errors.js";
+export * from "./exit-codes.js";
+export * from "./envelopes.js";
+export * from "./comments.js";
+export * from "./metadata.js";

package/dist/shared/src/contracts/cli/metadata.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/src/contracts/cli/operations.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/src/domain/comments/anchors.js

@@ -0,0 +1 @@
+export { addCommentToState, replyToCommentInState, setCommentStatusInState, deleteCommentInState, clearResolvedInState, syncAnchorsInState, normalizeAuthor } from "./parser.js";

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

@@ -0,0 +1,4 @@
+export * from "./parser.js";
+export * from "./serializer.js";
+export * from "./anchors.js";
+export * from "./thread-key.js";

package/dist/shared/src/domain/comments/serializer.js

@@ -0,0 +1 @@
+export { parseCommentAppendix, serializeCommentAppendix, upsertCommentAppendix, renderStateDocument, loadCommentDocumentState, serializeLoadedState, ensureNoParseErrors } from "./parser.js";

package/dist/shared/src/domain/comments/thread-key.js

@@ -0,0 +1,21 @@
+export function getCommentThreadKey(comment) {
+    const hasExplicitExcerptAnchor = comment.excerptStartLine !== undefined
+        && comment.excerptStartCol !== undefined
+        && comment.excerptEndLine !== undefined
+        && comment.excerptEndCol !== undefined
+        && (comment.excerptStartLine < comment.excerptEndLine
+            || (comment.excerptStartLine === comment.excerptEndLine && comment.excerptStartCol < comment.excerptEndCol));
+    if (hasExplicitExcerptAnchor) {
+        return [
+            "excerpt",
+            String(comment.paragraphIndex ?? -1),
+            String(comment.excerptStartLine),
+            String(comment.excerptStartCol),
+            String(comment.excerptEndLine),
+            String(comment.excerptEndCol)
+        ].join(":");
+    }
+    return comment.paragraphIndex !== undefined
+        ? `paragraph:${comment.paragraphIndex}`
+        : "file";
+}

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

@@ -0,0 +1,3 @@
+export * from "./parser.js";
+export * from "./serializer.js";
+export * from "./validators.js";

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

@@ -0,0 +1,34 @@
+import * as yaml from "js-yaml";
+export function parseMarkdownDocument(raw) {
+    const lineEnding = raw.includes("\r\n") ? "\r\n" : "\n";
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    if (!match) {
+        return {
+            lineEnding,
+            hasFrontmatter: false,
+            frontmatter: {},
+            body: raw
+        };
+    }
+    const yamlText = match[1];
+    const loaded = yamlText.trim().length > 0
+        ? yaml.load(yamlText)
+        : {};
+    if (loaded == null) {
+        return {
+            lineEnding,
+            hasFrontmatter: true,
+            frontmatter: {},
+            body: raw.slice(match[0].length)
+        };
+    }
+    if (typeof loaded !== "object" || Array.isArray(loaded)) {
+        throw new Error("Frontmatter must be a YAML object with key/value pairs.");
+    }
+    return {
+        lineEnding,
+        hasFrontmatter: true,
+        frontmatter: { ...loaded },
+        body: raw.slice(match[0].length)
+    };
+}

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

@@ -0,0 +1,32 @@
+import * as yaml from "js-yaml";
+export function orderFrontmatterStatusFirst(frontmatter) {
+    if (!Object.hasOwn(frontmatter, "status")) {
+        return { ...frontmatter };
+    }
+    const ordered = {
+        status: frontmatter.status
+    };
+    for (const [key, value] of Object.entries(frontmatter)) {
+        if (key === "status") {
+            continue;
+        }
+        ordered[key] = value;
+    }
+    return ordered;
+}
+export function serializeMarkdownDocument(parsed) {
+    const includeFrontmatter = parsed.hasFrontmatter || Object.keys(parsed.frontmatter).length > 0;
+    const normalizedBody = parsed.body.replace(/^\r?\n*/, "");
+    if (!includeFrontmatter) {
+        return parsed.body;
+    }
+    const ordered = orderFrontmatterStatusFirst(parsed.frontmatter);
+    const yamlBody = yaml.dump(ordered, { lineWidth: -1, noRefs: true }).trimEnd();
+    const frontmatterBlock = yamlBody.length > 0
+        ? `---${parsed.lineEnding}${yamlBody}${parsed.lineEnding}---`
+        : `---${parsed.lineEnding}---`;
+    if (!normalizedBody) {
+        return `${frontmatterBlock}${parsed.lineEnding}`;
+    }
+    return `${frontmatterBlock}${parsed.lineEnding}${parsed.lineEnding}${normalizedBody}`;
+}

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

@@ -0,0 +1,47 @@
+import * as yaml from "js-yaml";
+export function isValidMetadataKey(value) {
+    return /^[A-Za-z0-9_-]+$/.test(value);
+}
+export function parseMetadataInput(value) {
+    if (!value.trim()) {
+        return "";
+    }
+    const loaded = yaml.load(value);
+    return loaded === undefined ? value : loaded;
+}
+export function formatMetadataValue(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    const dumped = yaml.dump(value, { lineWidth: -1, noRefs: true }).trim();
+    return dumped || String(value);
+}
+export function normalizeFrontmatterRecord(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("Input payload 'frontmatter' must be a JSON object.");
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const normalizedKey = key.trim();
+        if (!normalizedKey) {
+            throw new Error("Frontmatter keys cannot be empty.");
+        }
+        result[normalizedKey] = normalizeFrontmatterValue(value, normalizedKey);
+    }
+    return result;
+}
+function normalizeFrontmatterValue(value, key) {
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeFrontmatterScalar(item, key));
+    }
+    return normalizeFrontmatterScalar(value, key);
+}
+function normalizeFrontmatterScalar(value, key) {
+    if (value === null) {
+        return null;
+    }
+    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.`);
+}

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

@@ -0,0 +1,4 @@
+export const PROJECT_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+export function isValidProjectId(value) {
+    return PROJECT_ID_PATTERN.test(value);
+}

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

@@ -0,0 +1,20 @@
+export const DEFAULT_ALLOWED_STATUSES = [
+    "draft",
+    "revise",
+    "line-edit",
+    "proof",
+    "final"
+];
+const STAGE_RANK = {
+    draft: 0,
+    revise: 1,
+    "line-edit": 2,
+    proof: 3,
+    final: 4
+};
+export function isStageName(value) {
+    return Object.hasOwn(STAGE_RANK, value);
+}
+export function getStageRank(stage) {
+    return STAGE_RANK[stage];
+}

package/dist/shared/src/index.js

@@ -0,0 +1,6 @@
+export * as CliContracts from "./contracts/cli/index.js";
+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 SharedUtils from "./utils/index.js";

package/dist/shared/src/utils/guards.js

@@ -0,0 +1,6 @@
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}

package/dist/shared/src/utils/index.js

@@ -0,0 +1,3 @@
+export * from "./result.js";
+export * from "./guards.js";
+export * from "./invariant.js";

package/dist/shared/src/utils/invariant.js

@@ -0,0 +1,5 @@
+export function invariant(condition, message) {
+    if (!condition) {
+        throw new Error(message);
+    }
+}

package/dist/shared/src/utils/result.js

@@ -0,0 +1,6 @@
+export function ok(value) {
+    return { ok: true, value };
+}
+export function err(error) {
+    return { ok: false, error };
+}

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

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+let cachedVersion = null;
+export function resolveCliVersion() {
+    if (cachedVersion) {
+        return cachedVersion;
+    }
+    let current = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        const packagePath = path.join(current, "package.json");
+        if (fs.existsSync(packagePath)) {
+            try {
+                const parsed = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+                if (parsed.name === "stego-cli" && typeof parsed.version === "string") {
+                    cachedVersion = parsed.version;
+                    return cachedVersion;
+                }
+            }
+            catch {
+                // Continue searching upward.
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    cachedVersion = "0.0.0";
+    return cachedVersion;
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,121 @@
+import { cac } from "cac";
+export class CommandRegistry {
+    cli;
+    appContext;
+    multiTokenCommandMappings = [];
+    constructor(appContext) {
+        this.appContext = appContext;
+        this.cli = cac("stego");
+    }
+    showHelp() {
+        this.cli.outputHelp();
+    }
+    register(spec) {
+        const commandName = normalizeRegisteredCommandName(spec.name, this.multiTokenCommandMappings);
+        let command = this.cli.command(commandName, spec.description);
+        for (const option of spec.options ?? []) {
+            const optionConfig = option.defaultValue === undefined
+                ? undefined
+                : { default: option.defaultValue };
+            command = command.option(option.flags, option.description ?? "", optionConfig);
+        }
+        if (spec.allowUnknownOptions) {
+            command = command.allowUnknownOptions();
+        }
+        command.action(async (...actionArgs) => {
+            const optionsCandidate = actionArgs[actionArgs.length - 1];
+            const options = isPlainObject(optionsCandidate)
+                ? sanitizeOptions(optionsCandidate)
+                : {};
+            const positionals = actionArgs
+                .slice(0, Math.max(0, actionArgs.length - 1))
+                .map((value) => String(value));
+            await spec.action({
+                ...this.appContext,
+                positionals,
+                options
+            });
+        });
+    }
+    run(argv) {
+        this.cli.help();
+        const normalizedArgv = normalizeDashInputValueArgv(normalizeIncomingArgv(argv, this.multiTokenCommandMappings));
+        this.cli.parse(["stego", "stego", ...normalizedArgv], { run: false });
+        if (!this.cli.matchedCommand) {
+            throw new Error("NO_MATCHED_COMMAND");
+        }
+        return this.cli.runMatchedCommand();
+    }
+}
+function normalizeRegisteredCommandName(rawName, mappings) {
+    const tokens = rawName.trim().split(/\s+/).filter(Boolean);
+    if (tokens.length <= 1) {
+        return rawName;
+    }
+    const commandTokens = [];
+    for (const token of tokens) {
+        if (token.startsWith("<") || token.startsWith("[")) {
+            break;
+        }
+        commandTokens.push(token);
+    }
+    if (commandTokens.length <= 1) {
+        return rawName;
+    }
+    const argumentTokens = tokens.slice(commandTokens.length);
+    const normalizedToken = commandTokens.join(":");
+    mappings.push({
+        rawTokens: commandTokens,
+        normalizedToken
+    });
+    return argumentTokens.length > 0
+        ? `${normalizedToken} ${argumentTokens.join(" ")}`
+        : normalizedToken;
+}
+function normalizeIncomingArgv(argv, mappings) {
+    if (argv.length === 0 || mappings.length === 0) {
+        return argv;
+    }
+    const sortedMappings = [...mappings]
+        .sort((a, b) => b.rawTokens.length - a.rawTokens.length);
+    for (const mapping of sortedMappings) {
+        if (!startsWithTokens(argv, mapping.rawTokens)) {
+            continue;
+        }
+        return [mapping.normalizedToken, ...argv.slice(mapping.rawTokens.length)];
+    }
+    return argv;
+}
+function normalizeDashInputValueArgv(argv) {
+    const normalized = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const current = argv[index];
+        const next = argv[index + 1];
+        if (current === "--input" && next === "-") {
+            normalized.push("--input=-");
+            index += 1;
+            continue;
+        }
+        normalized.push(current);
+    }
+    return normalized;
+}
+function startsWithTokens(input, expected) {
+    if (input.length < expected.length) {
+        return false;
+    }
+    for (let index = 0; index < expected.length; index += 1) {
+        if (input[index] !== expected[index]) {
+            return false;
+        }
+    }
+    return true;
+}
+function sanitizeOptions(options) {
+    const next = { ...options };
+    delete next["--"];
+    return next;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,42 @@
+import { CommandRegistry } from "./command-registry.js";
+import { coreModules } from "../modules/index.js";
+import { CliError } from "../../../shared/src/contracts/cli/index.js";
+import { writeText } from "./output-renderer.js";
+import { resolveCliVersion } from "./cli-version.js";
+export function createCliApp(appContext) {
+    const registry = new CommandRegistry(appContext);
+    for (const module of coreModules) {
+        module.registerCommands(registry);
+    }
+    return {
+        run: async () => {
+            const [firstArg] = appContext.argv;
+            if (!firstArg || isHelpRequest(firstArg)) {
+                registry.showHelp();
+                return;
+            }
+            if (isVersionRequest(firstArg)) {
+                writeText(resolveCliVersion());
+                return;
+            }
+            try {
+                await registry.run(appContext.argv);
+            }
+            catch (error) {
+                if (isNoMatchedCommandError(error)) {
+                    throw new CliError("INVALID_USAGE", `Unknown command '${firstArg}'. Run 'stego --help' for usage.`);
+                }
+                throw error;
+            }
+        }
+    };
+}
+function isNoMatchedCommandError(error) {
+    return error instanceof Error && error.message === "NO_MATCHED_COMMAND";
+}
+function isHelpRequest(arg) {
+    return arg === "help" || arg === "--help" || arg === "-h";
+}
+function isVersionRequest(arg) {
+    return arg === "version" || arg === "--version" || arg === "-v";
+}

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

@@ -0,0 +1,42 @@
+function shouldRenderJsonError(argv) {
+    return argv.includes("--format") && argv.includes("json");
+}
+function errorEnvelope(code, message, details) {
+    return {
+        ok: false,
+        version: 1,
+        code,
+        message,
+        details
+    };
+}
+export async function runWithErrorBoundary(argv, run) {
+    try {
+        await run();
+    }
+    catch (error) {
+        if (isCliLikeError(error)) {
+            if (shouldRenderJsonError(argv)) {
+                writeJsonError(errorEnvelope(error.code || "INTERNAL_ERROR", error.message, error.details));
+            }
+            else {
+                process.stderr.write(`ERROR: ${error.message}\n`);
+            }
+            process.exit(error.exitCode ?? 1);
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        if (shouldRenderJsonError(argv)) {
+            writeJsonError(errorEnvelope("INTERNAL_ERROR", message));
+        }
+        else {
+            process.stderr.write(`ERROR: ${message}\n`);
+        }
+        process.exit(1);
+    }
+}
+function writeJsonError(payload) {
+    process.stderr.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+function isCliLikeError(value) {
+    return typeof value === "object" && value !== null && "message" in value;
+}

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

@@ -0,0 +1,6 @@
+export * from "./command-context.js";
+export * from "./command-registry.js";
+export * from "./cli-version.js";
+export * from "./create-cli-app.js";
+export * from "./error-boundary.js";
+export * from "./output-renderer.js";

package/dist/stego-cli/src/app/output-renderer.js

@@ -0,0 +1,6 @@
+export function writeText(message) {
+    process.stdout.write(`${message}\n`);
+}
+export function writeJson(payload) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}

package/dist/stego-cli/src/main.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { createCliApp } from "./app/create-cli-app.js";
+import { runWithErrorBoundary } from "./app/error-boundary.js";
+const app = createCliApp({
+    argv: process.argv.slice(2),
+    cwd: process.cwd(),
+    env: process.env,
+    stdout: process.stdout,
+    stderr: process.stderr
+});
+await runWithErrorBoundary(process.argv.slice(2), async () => {
+    await app.run();
+});