stego-cli 0.3.4 → 0.4.1

package/.vscode/extensions.json

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

package/README.md

@@ -54,12 +54,57 @@ 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 metadata read projects/fiction-example/manuscript/100-the-commission.md --format json
 ```
 
 `stego new` also supports `--i <prefix>` for numeric prefix override and `--filename <name>` for an explicit manuscript filename.
 
+Spine V2 is directory-inferred:
+
+- categories are directories in `spine/<category>/`
+- category metadata lives at `spine/<category>/_category.md`
+- entries are markdown files in each category directory tree
+
 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/metadata/metadata-command.js

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { normalizeFrontmatterRecord, parseMarkdownDocument, serializeMarkdownDocument } from "./metadata-domain.js";
+export async function runMetadataCommand(options, cwd) {
+    const [subcommand, markdownArg] = options._;
+    if (!subcommand) {
+        throw new Error("Metadata subcommand is required. Use: read, apply.");
+    }
+    if (!markdownArg) {
+        throw new Error("Markdown path is required. Use: stego metadata <subcommand> <path>.");
+    }
+    const outputFormat = parseOutputFormat(readString(options, "format"));
+    const absolutePath = path.resolve(cwd, markdownArg);
+    const raw = readFile(absolutePath, markdownArg);
+    switch (subcommand) {
+        case "read": {
+            const parsed = parseMarkdownDocument(raw);
+            emit({
+                ok: true,
+                operation: "read",
+                state: {
+                    path: absolutePath,
+                    hasFrontmatter: parsed.hasFrontmatter,
+                    lineEnding: parsed.lineEnding,
+                    frontmatter: parsed.frontmatter,
+                    body: parsed.body
+                }
+            }, outputFormat);
+            return;
+        }
+        case "apply": {
+            const inputPath = requireInputPath(options);
+            const payload = readInputPayload(inputPath, cwd);
+            const frontmatter = normalizeFrontmatterRecord(payload.frontmatter);
+            const body = typeof payload.body === "string" ? payload.body : undefined;
+            const hasFrontmatter = typeof payload.hasFrontmatter === "boolean" ? payload.hasFrontmatter : undefined;
+            const existing = parseMarkdownDocument(raw);
+            const next = {
+                lineEnding: existing.lineEnding,
+                hasFrontmatter: hasFrontmatter ?? (existing.hasFrontmatter || Object.keys(frontmatter).length > 0),
+                frontmatter,
+                body: body ?? existing.body
+            };
+            const nextText = serializeMarkdownDocument(next);
+            const changed = nextText !== raw;
+            if (changed) {
+                fs.writeFileSync(absolutePath, nextText, "utf8");
+            }
+            const reparsed = parseMarkdownDocument(nextText);
+            emit({
+                ok: true,
+                operation: "apply",
+                changed,
+                state: {
+                    path: absolutePath,
+                    hasFrontmatter: reparsed.hasFrontmatter,
+                    lineEnding: reparsed.lineEnding,
+                    frontmatter: reparsed.frontmatter,
+                    body: reparsed.body
+                }
+            }, outputFormat);
+            return;
+        }
+        default:
+            throw new Error(`Unknown metadata subcommand '${subcommand}'. Use: read, apply.`);
+    }
+}
+function emit(payload, format) {
+    if (format === "json") {
+        process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return;
+    }
+    if (payload.operation === "read") {
+        process.stdout.write(`Read metadata for ${payload.state.path} (${Object.keys(payload.state.frontmatter).length} keys).\n`);
+        return;
+    }
+    process.stdout.write(`${payload.changed ? "Updated" : "No changes for"} metadata in ${payload.state.path}.\n`);
+}
+function parseOutputFormat(raw) {
+    if (!raw || raw === "text") {
+        return "text";
+    }
+    if (raw === "json") {
+        return "json";
+    }
+    throw new Error("Invalid --format value. Use 'text' or 'json'.");
+}
+function readString(options, key) {
+    const value = options[key];
+    return typeof value === "string" ? value : undefined;
+}
+function requireInputPath(options) {
+    const inputPath = readString(options, "input");
+    if (!inputPath) {
+        throw new Error("--input <path|-> is required for 'metadata apply'.");
+    }
+    return inputPath;
+}
+function readInputPayload(inputPath, cwd) {
+    const raw = inputPath === "-"
+        ? fs.readFileSync(process.stdin.fd, "utf8")
+        : fs.readFileSync(path.resolve(cwd, inputPath), "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Input payload is not valid JSON.");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Input payload must be a JSON object.");
+    }
+    return parsed;
+}
+function readFile(filePath, originalArg) {
+    try {
+        const stat = fs.statSync(filePath);
+        if (!stat.isFile()) {
+            throw new Error();
+        }
+    }
+    catch {
+        throw new Error(`Markdown file not found: ${originalArg}`);
+    }
+    return fs.readFileSync(filePath, "utf8");
+}

package/dist/metadata/metadata-domain.js

@@ -0,0 +1,209 @@
+import path from "node:path";
+export function parseMarkdownDocument(raw) {
+    const lineEnding = raw.includes("\r\n") ? "\r\n" : "\n";
+    if (!raw.startsWith("---\n") && !raw.startsWith("---\r\n")) {
+        return {
+            lineEnding,
+            hasFrontmatter: false,
+            frontmatter: {},
+            body: raw
+        };
+    }
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!match) {
+        throw new Error("Metadata opening delimiter found, but closing delimiter is missing.");
+    }
+    const frontmatterText = match[1];
+    const body = raw.slice(match[0].length);
+    const frontmatter = {};
+    const lines = frontmatterText.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i].trim();
+        if (!line || line.startsWith("#")) {
+            continue;
+        }
+        const separatorIndex = line.indexOf(":");
+        if (separatorIndex < 0) {
+            throw new Error(`Invalid metadata line '${line}'. Expected 'key: value'.`);
+        }
+        const key = line.slice(0, separatorIndex).trim();
+        const value = line.slice(separatorIndex + 1).trim();
+        if (!key) {
+            throw new Error(`Invalid metadata line '${line}'. Missing key.`);
+        }
+        if (!value) {
+            let lookahead = i + 1;
+            while (lookahead < lines.length) {
+                const nextTrimmed = lines[lookahead].trim();
+                if (!nextTrimmed || nextTrimmed.startsWith("#")) {
+                    lookahead += 1;
+                    continue;
+                }
+                break;
+            }
+            if (lookahead < lines.length) {
+                const firstItemLine = lines[lookahead];
+                const firstItemTrimmed = firstItemLine.trim();
+                const firstItemIndent = firstItemLine.length - firstItemLine.trimStart().length;
+                if (firstItemIndent > 0 && firstItemTrimmed.startsWith("- ")) {
+                    const items = [];
+                    let j = lookahead;
+                    while (j < lines.length) {
+                        const rawCandidate = lines[j];
+                        const trimmed = rawCandidate.trim();
+                        if (!trimmed || trimmed.startsWith("#")) {
+                            j += 1;
+                            continue;
+                        }
+                        const indent = rawCandidate.length - rawCandidate.trimStart().length;
+                        if (indent === 0) {
+                            break;
+                        }
+                        if (!trimmed.startsWith("- ")) {
+                            throw new Error(`Unsupported metadata list line '${trimmed}'. Expected '- value'.`);
+                        }
+                        items.push(coerceScalarValue(trimmed.slice(2).trim()));
+                        j += 1;
+                    }
+                    frontmatter[key] = items;
+                    i = j - 1;
+                    continue;
+                }
+            }
+        }
+        frontmatter[key] = coerceScalarValue(value);
+    }
+    return {
+        lineEnding,
+        hasFrontmatter: true,
+        frontmatter,
+        body
+    };
+}
+export function serializeMarkdownDocument(parsed) {
+    const lineEnding = parsed.lineEnding || "\n";
+    const includeFrontmatter = parsed.hasFrontmatter || Object.keys(parsed.frontmatter).length > 0;
+    const normalizedBody = normalizeBodyLineEndings(parsed.body || "", lineEnding);
+    if (!includeFrontmatter) {
+        return normalizedBody;
+    }
+    const ordered = orderFrontmatterStatusFirst(parsed.frontmatter);
+    const yamlLines = [];
+    for (const key of Object.keys(ordered)) {
+        const value = ordered[key];
+        if (Array.isArray(value)) {
+            yamlLines.push(`${key}:`);
+            for (const item of value) {
+                yamlLines.push(`  - ${formatScalar(item)}`);
+            }
+            continue;
+        }
+        yamlLines.push(`${key}: ${formatScalar(value)}`);
+    }
+    const frontmatterBlock = yamlLines.length > 0
+        ? `---${lineEnding}${yamlLines.join(lineEnding)}${lineEnding}---`
+        : `---${lineEnding}---`;
+    if (!normalizedBody.trim()) {
+        return `${frontmatterBlock}${lineEnding}`;
+    }
+    const trimmedBody = normalizedBody.replace(/^(\r?\n)+/, "");
+    return `${frontmatterBlock}${lineEnding}${lineEnding}${trimmedBody}`;
+}
+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;
+}
+export function deriveDefaultLabelFromFilename(filePath) {
+    const basename = path.basename(filePath, path.extname(filePath));
+    const normalized = basename
+        .replace(/[_-]+/g, " ")
+        .trim();
+    if (!normalized) {
+        return "New Entry";
+    }
+    return normalized.replace(/\b\w/g, (value) => value.toUpperCase());
+}
+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;
+}
+function normalizeBodyLineEndings(body, lineEnding) {
+    return body.replace(/\r?\n/g, lineEnding);
+}
+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.`);
+}
+function coerceScalarValue(rawValue) {
+    const value = rawValue.trim();
+    if (!value) {
+        return "";
+    }
+    if ((value.startsWith("\"") && value.endsWith("\"")) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    if (value === "null") {
+        return null;
+    }
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    if (/^-?\d+$/.test(value)) {
+        return Number(value);
+    }
+    return value;
+}
+function formatScalar(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    const normalized = value.trim();
+    if (!normalized) {
+        return "\"\"";
+    }
+    if (/^-?\d+$/.test(normalized) || normalized === "true" || normalized === "false" || normalized === "null") {
+        return JSON.stringify(normalized);
+    }
+    if (/^[A-Za-z0-9._/@:+-]+$/.test(normalized)) {
+        return normalized;
+    }
+    return JSON.stringify(normalized);
+}

package/dist/spine/spine-command.js

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { createSpineCategory, createSpineEntry, readSpineCatalog } from "./spine-domain.js";
+export function runSpineCommand(options, project) {
+    const [subcommand] = options._;
+    if (!subcommand) {
+        throw new Error("Spine subcommand is required. Use: read, new-category, new.");
+    }
+    if (subcommand === "add-category") {
+        throw new Error("`stego spine add-category` is deprecated. Use `stego spine new-category`.");
+    }
+    if (subcommand === "new-entry") {
+        throw new Error("`stego spine new-entry` is deprecated. Use `stego spine new`.");
+    }
+    const outputFormat = parseOutputFormat(readString(options, "format"));
+    switch (subcommand) {
+        case "read": {
+            const catalog = readSpineCatalog(project.root, project.spineDir);
+            emit({
+                ok: true,
+                operation: "read",
+                state: {
+                    projectId: project.id,
+                    categories: catalog.categories,
+                    issues: catalog.issues
+                }
+            }, outputFormat);
+            return;
+        }
+        case "new-category": {
+            const key = readString(options, "key");
+            if (!key) {
+                throw new Error("--key is required for `stego spine new-category`.");
+            }
+            const label = readString(options, "label");
+            const requireMetadata = options["require-metadata"] === true;
+            const requiredMetadata = readRequiredMetadata(project.meta);
+            const result = createSpineCategory(project.root, project.spineDir, key, label, requiredMetadata, requireMetadata);
+            if (requireMetadata && result.requiredMetadataUpdated) {
+                writeRequiredMetadata(project.root, project.meta, requiredMetadata);
+            }
+            emit({
+                ok: true,
+                operation: "new-category",
+                result
+            }, outputFormat);
+            return;
+        }
+        case "new": {
+            const category = readString(options, "category");
+            if (!category) {
+                throw new Error("--category is required for `stego spine new`.");
+            }
+            if (options.entry !== undefined) {
+                throw new Error("Unknown option '--entry' for `stego spine new`. Use `--filename`.");
+            }
+            const filename = readString(options, "filename");
+            const result = createSpineEntry(project.root, project.spineDir, category, filename);
+            emit({
+                ok: true,
+                operation: "new",
+                result
+            }, outputFormat);
+            return;
+        }
+        default:
+            throw new Error(`Unknown spine subcommand '${subcommand}'. Use: read, new-category, new.`);
+    }
+}
+function emit(payload, outputFormat) {
+    if (outputFormat === "json") {
+        process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return;
+    }
+    switch (payload.operation) {
+        case "read":
+            process.stdout.write(`Spine categories: ${payload.state.categories.length}. ` +
+                `Entries: ${payload.state.categories.reduce((sum, category) => sum + category.entries.length, 0)}.\n`);
+            return;
+        case "new-category":
+            process.stdout.write(`Created spine category '${payload.result.key}' (${payload.result.metadataPath}).\n`);
+            return;
+        case "new":
+            process.stdout.write(`Created spine entry: ${payload.result.filePath}\n`);
+            return;
+    }
+}
+function parseOutputFormat(raw) {
+    if (!raw || raw === "text") {
+        return "text";
+    }
+    if (raw === "json") {
+        return "json";
+    }
+    throw new Error("Invalid --format value. Use 'text' or 'json'.");
+}
+function readString(options, key) {
+    const value = options[key];
+    return typeof value === "string" ? value : undefined;
+}
+function readRequiredMetadata(projectMeta) {
+    const raw = projectMeta.requiredMetadata;
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    const seen = new Set();
+    const keys = [];
+    for (const entry of raw) {
+        if (typeof entry !== "string") {
+            continue;
+        }
+        const key = entry.trim();
+        if (!key || seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        keys.push(key);
+    }
+    return keys;
+}
+function writeRequiredMetadata(projectRoot, projectMeta, requiredMetadata) {
+    const projectJsonPath = path.join(projectRoot, "stego-project.json");
+    const next = {
+        ...projectMeta,
+        requiredMetadata
+    };
+    fs.writeFileSync(projectJsonPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+}