stego-cli 0.3.3 → 0.4.0

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");
+}

package/dist/spine/spine-domain.js

@@ -0,0 +1,274 @@
+import fs from "node:fs";
+import path from "node:path";
+import { deriveDefaultLabelFromFilename, parseMarkdownDocument, serializeMarkdownDocument } from "../metadata/metadata-domain.js";
+const CATEGORY_KEY_PATTERN = /^[A-Za-z0-9_-]+$/;
+export function readSpineCatalog(projectRoot, spineDir) {
+    const absoluteSpineDir = path.resolve(spineDir);
+    const issues = [];
+    const categories = [];
+    const entriesByCategory = new Map();
+    if (!fs.existsSync(absoluteSpineDir)) {
+        return { categories, entriesByCategory, issues: [`Missing spine directory: ${absoluteSpineDir}`] };
+    }
+    const categoryDirs = fs
+        .readdirSync(absoluteSpineDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+        .map((entry) => entry.name)
+        .sort((a, b) => a.localeCompare(b));
+    for (const categoryKey of categoryDirs) {
+        if (!CATEGORY_KEY_PATTERN.test(categoryKey)) {
+            issues.push(`Ignored invalid spine category directory '${categoryKey}'.`);
+            continue;
+        }
+        const categoryDir = path.join(absoluteSpineDir, categoryKey);
+        const metadataPath = path.join(categoryDir, "_category.md");
+        const categoryLabel = readCategoryLabel(metadataPath, categoryKey);
+        const entryFiles = collectEntryFiles(categoryDir);
+        const entries = [];
+        const knownKeys = new Set();
+        for (const entryFile of entryFiles) {
+            const key = toEntryKey(categoryDir, entryFile);
+            if (!key) {
+                continue;
+            }
+            if (knownKeys.has(key)) {
+                continue;
+            }
+            knownKeys.add(key);
+            const entryMeta = readEntryPreview(entryFile);
+            entries.push({
+                key,
+                path: path.relative(projectRoot, entryFile).split(path.sep).join("/"),
+                label: entryMeta.label,
+                title: entryMeta.title,
+                description: entryMeta.description
+            });
+        }
+        entries.sort((a, b) => a.key.localeCompare(b.key));
+        entriesByCategory.set(categoryKey, knownKeys);
+        categories.push({
+            key: categoryKey,
+            label: categoryLabel,
+            path: path.relative(projectRoot, categoryDir).split(path.sep).join("/"),
+            metadataPath: path.relative(projectRoot, metadataPath).split(path.sep).join("/"),
+            entries
+        });
+        if (!fs.existsSync(metadataPath)) {
+            issues.push(`Missing category metadata file: ${metadataPath}`);
+        }
+    }
+    return { categories, entriesByCategory, issues };
+}
+export function createSpineCategory(projectRoot, spineDir, keyRaw, labelRaw, requiredMetadata, updateRequiredMetadata) {
+    const key = normalizeCategoryKey(keyRaw);
+    if (!key) {
+        throw new Error("Category key is required.");
+    }
+    if (!CATEGORY_KEY_PATTERN.test(key)) {
+        throw new Error(`Invalid category key '${key}'. Use letters, numbers, '_' or '-'.`);
+    }
+    const categoryDir = path.join(path.resolve(spineDir), key);
+    fs.mkdirSync(categoryDir, { recursive: true });
+    const label = (labelRaw || "").trim() || toDisplayLabel(key);
+    const metadataPath = path.join(categoryDir, "_category.md");
+    if (!fs.existsSync(metadataPath)) {
+        const frontmatter = { label };
+        const rendered = serializeMarkdownDocument({
+            lineEnding: "\n",
+            hasFrontmatter: true,
+            frontmatter,
+            body: `# ${label}\n\n`
+        });
+        fs.writeFileSync(metadataPath, rendered, "utf8");
+    }
+    let requiredMetadataUpdated = false;
+    if (updateRequiredMetadata) {
+        const normalizedRequired = new Set(requiredMetadata.map((value) => value.trim()).filter(Boolean));
+        if (!normalizedRequired.has(key)) {
+            normalizedRequired.add(key);
+            requiredMetadata.splice(0, requiredMetadata.length, ...Array.from(normalizedRequired));
+            requiredMetadataUpdated = true;
+        }
+    }
+    return {
+        key,
+        label,
+        categoryDir: path.relative(projectRoot, categoryDir).split(path.sep).join("/"),
+        metadataPath: path.relative(projectRoot, metadataPath).split(path.sep).join("/"),
+        requiredMetadataUpdated
+    };
+}
+export function createSpineEntry(projectRoot, spineDir, categoryRaw, filenameRaw) {
+    const category = normalizeCategoryKey(categoryRaw);
+    if (!category) {
+        throw new Error("--category is required.");
+    }
+    if (!CATEGORY_KEY_PATTERN.test(category)) {
+        throw new Error(`Invalid category key '${category}'. Use letters, numbers, '_' or '-'.`);
+    }
+    const categoryDir = path.join(path.resolve(spineDir), category);
+    if (!fs.existsSync(categoryDir)) {
+        throw new Error(`Spine category '${category}' does not exist. Run 'stego spine new-category --key ${category}' first.`);
+    }
+    const filename = normalizeEntryFilename(filenameRaw);
+    const fullPath = path.resolve(path.join(categoryDir, filename));
+    const relativeToCategory = path.relative(categoryDir, fullPath).split(path.sep).join("/");
+    if (!relativeToCategory || relativeToCategory.startsWith("..") || path.isAbsolute(relativeToCategory)) {
+        throw new Error(`Invalid filename '${filename}'. Use a path inside category '${category}'.`);
+    }
+    if (!fullPath.toLowerCase().endsWith(".md")) {
+        throw new Error(`Invalid filename '${filename}'. Use markdown file paths.`);
+    }
+    if (fs.existsSync(fullPath)) {
+        throw new Error(`Spine entry already exists: ${fullPath}`);
+    }
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+    const inferredLabel = deriveDefaultLabelFromFilename(fullPath);
+    const rendered = serializeMarkdownDocument({
+        lineEnding: "\n",
+        hasFrontmatter: false,
+        frontmatter: {},
+        body: `# ${inferredLabel}\n\n`
+    });
+    fs.writeFileSync(fullPath, rendered, "utf8");
+    return {
+        category,
+        entryKey: toEntryKey(categoryDir, fullPath) || path.basename(fullPath, ".md"),
+        filePath: path.relative(projectRoot, fullPath).split(path.sep).join("/")
+    };
+}
+export function toDisplayLabel(value) {
+    const normalized = value
+        .replace(/[_-]+/g, " ")
+        .trim();
+    if (!normalized) {
+        return value;
+    }
+    return normalized.replace(/\b\w/g, (part) => part.toUpperCase());
+}
+function readCategoryLabel(metadataPath, categoryKey) {
+    if (!fs.existsSync(metadataPath)) {
+        return toDisplayLabel(categoryKey);
+    }
+    try {
+        const raw = fs.readFileSync(metadataPath, "utf8");
+        const parsed = parseMarkdownDocument(raw);
+        const fromFrontmatter = typeof parsed.frontmatter.label === "string" ? parsed.frontmatter.label.trim() : "";
+        if (fromFrontmatter) {
+            return fromFrontmatter;
+        }
+        const heading = findFirstHeading(parsed.body);
+        if (heading) {
+            return heading;
+        }
+    }
+    catch {
+        // fallback below
+    }
+    return toDisplayLabel(categoryKey);
+}
+function readEntryPreview(filePath) {
+    const fallback = deriveDefaultLabelFromFilename(filePath);
+    try {
+        const raw = fs.readFileSync(filePath, "utf8");
+        const parsed = parseMarkdownDocument(raw);
+        const heading = findFirstHeading(parsed.body);
+        const labelFromFrontmatter = typeof parsed.frontmatter.label === "string" ? parsed.frontmatter.label.trim() : "";
+        const label = labelFromFrontmatter || heading || fallback;
+        const title = heading || label || fallback;
+        const description = firstContentLine(parsed.body, heading).slice(0, 220);
+        return { label, title, description };
+    }
+    catch {
+        return { label: fallback, title: fallback, description: "" };
+    }
+}
+function collectEntryFiles(categoryDir) {
+    const files = [];
+    const stack = [path.resolve(categoryDir)];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current) {
+            continue;
+        }
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            if (entry.name.startsWith(".")) {
+                continue;
+            }
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md")) {
+                continue;
+            }
+            if (entry.name.toLowerCase() === "_category.md") {
+                continue;
+            }
+            files.push(full);
+        }
+    }
+    return files.sort((a, b) => a.localeCompare(b));
+}
+function normalizeCategoryKey(rawValue) {
+    return rawValue.trim().toLowerCase();
+}
+function normalizeEntryFilename(rawValue) {
+    const trimmed = (rawValue || "").trim();
+    const fallback = "new-entry.md";
+    const withFallback = trimmed || fallback;
+    const withExt = withFallback.toLowerCase().endsWith(".md") ? withFallback : `${withFallback}.md`;
+    const normalized = withExt.replace(/\\/g, "/");
+    if (normalized.startsWith("/") || normalized.includes("../") || normalized.startsWith("../")) {
+        throw new Error(`Invalid filename '${rawValue || ""}'.`);
+    }
+    return normalized;
+}
+function toEntryKey(categoryDir, filePath) {
+    const relative = path.relative(categoryDir, filePath).split(path.sep).join("/");
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        return undefined;
+    }
+    if (!relative.toLowerCase().endsWith(".md")) {
+        return undefined;
+    }
+    return relative.slice(0, -3);
+}
+function findFirstHeading(body) {
+    for (const line of body.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        const match = trimmed.match(/^#{1,6}\s+(.+?)\s*$/);
+        if (match) {
+            return match[1].trim();
+        }
+    }
+    return undefined;
+}
+function firstContentLine(body, heading) {
+    const lines = body.split(/\r?\n/);
+    let skippedHeading = !heading;
+    for (const rawLine of lines) {
+        const trimmed = rawLine.trim();
+        if (!trimmed) {
+            continue;
+        }
+        if (!skippedHeading && /^#{1,6}\s+/.test(trimmed)) {
+            skippedHeading = true;
+            continue;
+        }
+        if (trimmed.startsWith("<!--")) {
+            continue;
+        }
+        return trimmed;
+    }
+    return "";
+}