stego-cli 0.4.0 → 0.4.2

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

@@ -0,0 +1,64 @@
+import { CliError } from "../../../../../shared/src/contracts/cli/index.js";
+import { writeJson, writeText } from "../../../app/output-renderer.js";
+import { resolveProjectContext } from "../../project/index.js";
+import { resolveWorkspaceContext } from "../../workspace/index.js";
+import { createSpineCategoryForProject } from "../application/create-category.js";
+import { parseSpineOutputFormat } from "../infra/spine-repo.js";
+export function registerSpineNewCategoryCommand(registry) {
+    registry.register({
+        name: "spine new-category",
+        description: "Create a new spine category",
+        allowUnknownOptions: true,
+        options: [
+            { flags: "--project <project-id>", description: "Project id" },
+            { flags: "--key <category>", description: "Category key" },
+            { flags: "--label <label>", description: "Category display label" },
+            { flags: "--require-metadata", description: "Append key to required metadata" },
+            { flags: "--format <format>", description: "text|json" },
+            { flags: "--root <path>", description: "Workspace root path" }
+        ],
+        action: (context) => {
+            const key = readStringOption(context.options, "key");
+            if (!key) {
+                throw new CliError("INVALID_USAGE", "--key is required for `stego spine new-category`.");
+            }
+            const outputFormat = parseSpineOutputFormat(readOption(context.options, "format"));
+            const project = resolveProjectContext({
+                workspace: resolveWorkspaceContext({
+                    cwd: context.cwd,
+                    rootOption: readStringOption(context.options, "root")
+                }),
+                cwd: context.cwd,
+                env: context.env,
+                explicitProjectId: readStringOption(context.options, "project")
+            });
+            const result = createSpineCategoryForProject({
+                project,
+                key,
+                label: readStringOption(context.options, "label"),
+                requireMetadata: readBooleanOption(context.options, "requireMetadata")
+            });
+            if (outputFormat === "json") {
+                writeJson(result);
+                return;
+            }
+            writeText(`Created spine category '${result.result.key}' (${result.result.metadataPath}).`);
+        }
+    });
+}
+function readOption(options, key) {
+    return options[key];
+}
+function readStringOption(options, key) {
+    const value = options[key];
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return String(value);
+    }
+    return undefined;
+}
+function readBooleanOption(options, key) {
+    return options[key] === true;
+}

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

@@ -0,0 +1,65 @@
+import { CliError } from "../../../../../shared/src/contracts/cli/index.js";
+import { writeJson, writeText } from "../../../app/output-renderer.js";
+import { resolveProjectContext } from "../../project/index.js";
+import { resolveWorkspaceContext } from "../../workspace/index.js";
+import { createSpineEntryForProject } from "../application/create-entry.js";
+import { parseSpineOutputFormat } from "../infra/spine-repo.js";
+export function registerSpineNewEntryCommand(registry) {
+    registry.register({
+        name: "spine new",
+        description: "Create a new spine entry",
+        allowUnknownOptions: true,
+        options: [
+            { flags: "--project <project-id>", description: "Project id" },
+            { flags: "--category <category>", description: "Category key" },
+            { flags: "--filename <path>", description: "Relative entry path" },
+            { flags: "--format <format>", description: "text|json" },
+            { flags: "--root <path>", description: "Workspace root path" }
+        ],
+        action: (context) => {
+            if (hasOption(context.options, "entry")) {
+                throw new Error("Unknown option '--entry' for `stego spine new`. Use `--filename`.");
+            }
+            const category = readStringOption(context.options, "category");
+            if (!category) {
+                throw new CliError("INVALID_USAGE", "--category is required for `stego spine new`.");
+            }
+            const outputFormat = parseSpineOutputFormat(readOption(context.options, "format"));
+            const project = resolveProjectContext({
+                workspace: resolveWorkspaceContext({
+                    cwd: context.cwd,
+                    rootOption: readStringOption(context.options, "root")
+                }),
+                cwd: context.cwd,
+                env: context.env,
+                explicitProjectId: readStringOption(context.options, "project")
+            });
+            const result = createSpineEntryForProject({
+                project,
+                category,
+                filename: readStringOption(context.options, "filename")
+            });
+            if (outputFormat === "json") {
+                writeJson(result);
+                return;
+            }
+            writeText(`Created spine entry: ${result.result.filePath}`);
+        }
+    });
+}
+function readOption(options, key) {
+    return options[key];
+}
+function readStringOption(options, key) {
+    const value = options[key];
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return String(value);
+    }
+    return undefined;
+}
+function hasOption(options, key) {
+    return Object.hasOwn(options, key);
+}

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

@@ -0,0 +1,49 @@
+import { writeJson, writeText } from "../../../app/output-renderer.js";
+import { resolveProjectContext } from "../../project/index.js";
+import { resolveWorkspaceContext } from "../../workspace/index.js";
+import { readSpineCatalogForProject } from "../application/read-catalog.js";
+import { parseSpineOutputFormat } from "../infra/spine-repo.js";
+export function registerSpineReadCommand(registry) {
+    registry.register({
+        name: "spine read",
+        description: "Read spine catalog",
+        allowUnknownOptions: true,
+        options: [
+            { flags: "--project <project-id>", description: "Project id" },
+            { flags: "--format <format>", description: "text|json" },
+            { flags: "--root <path>", description: "Workspace root path" }
+        ],
+        action: (context) => {
+            const outputFormat = parseSpineOutputFormat(readOption(context.options, "format"));
+            const project = resolveProjectContext({
+                workspace: resolveWorkspaceContext({
+                    cwd: context.cwd,
+                    rootOption: readStringOption(context.options, "root")
+                }),
+                cwd: context.cwd,
+                env: context.env,
+                explicitProjectId: readStringOption(context.options, "project")
+            });
+            const result = readSpineCatalogForProject(project);
+            if (outputFormat === "json") {
+                writeJson(result);
+                return;
+            }
+            const entryCount = result.state.categories.reduce((sum, category) => sum + category.entries.length, 0);
+            writeText(`Spine categories: ${result.state.categories.length}. Entries: ${entryCount}.`);
+        }
+    });
+}
+function readOption(options, key) {
+    return options[key];
+}
+function readStringOption(options, key) {
+    const value = options[key];
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return String(value);
+    }
+    return undefined;
+}

package/dist/{spine/spine-domain.js → stego-cli/src/modules/spine/domain/spine.js}

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { deriveDefaultLabelFromFilename, parseMarkdownDocument, serializeMarkdownDocument } from "../metadata/metadata-domain.js";
+import { parseMarkdownDocument, serializeMarkdownDocument } from "../../../../../shared/src/domain/frontmatter/index.js";
 const CATEGORY_KEY_PATTERN = /^[A-Za-z0-9_-]+$/;
 export function readSpineCatalog(projectRoot, spineDir) {
     const absoluteSpineDir = path.resolve(spineDir);
@@ -28,10 +28,7 @@ export function readSpineCatalog(projectRoot, spineDir) {
         const knownKeys = new Set();
         for (const entryFile of entryFiles) {
             const key = toEntryKey(categoryDir, entryFile);
-            if (!key) {
-                continue;
-            }
-            if (knownKeys.has(key)) {
+            if (!key || knownKeys.has(key)) {
                 continue;
             }
             knownKeys.add(key);
@@ -72,11 +69,10 @@ export function createSpineCategory(projectRoot, spineDir, keyRaw, labelRaw, req
     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,
+            frontmatter: { label },
             body: `# ${label}\n\n`
         });
         fs.writeFileSync(metadataPath, rendered, "utf8");
@@ -272,3 +268,13 @@ function firstContentLine(body, heading) {
     }
     return "";
 }
+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, (part) => part.toUpperCase());
+}

package/dist/stego-cli/src/modules/spine/index.js

@@ -0,0 +1,16 @@
+import { registerSpineReadCommand } from "./commands/spine-read.js";
+import { registerSpineNewCategoryCommand } from "./commands/spine-new-category.js";
+import { registerSpineNewEntryCommand } from "./commands/spine-new-entry.js";
+import { registerSpineDeprecatedAliases } from "./commands/spine-deprecated-aliases.js";
+export const spineModule = {
+    registerCommands(registry) {
+        registerSpineReadCommand(registry);
+        registerSpineNewCategoryCommand(registry);
+        registerSpineNewEntryCommand(registry);
+        registerSpineDeprecatedAliases(registry);
+    }
+};
+export * from "./types.js";
+export * from "./application/read-catalog.js";
+export * from "./application/create-category.js";
+export * from "./application/create-entry.js";

package/dist/stego-cli/src/modules/spine/infra/spine-repo.js

@@ -0,0 +1,46 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CliError } from "../../../../../shared/src/contracts/cli/index.js";
+export function parseSpineOutputFormat(rawValue) {
+    if (rawValue === undefined || rawValue === null || rawValue === "text") {
+        return "text";
+    }
+    if (rawValue === "json") {
+        return "json";
+    }
+    throw new CliError("INVALID_USAGE", "Invalid --format value. Use 'text' or 'json'.");
+}
+export function readRequiredMetadata(projectMeta) {
+    const rawValue = projectMeta.requiredMetadata;
+    if (!Array.isArray(rawValue)) {
+        return [];
+    }
+    const seen = new Set();
+    const keys = [];
+    for (const candidate of rawValue) {
+        if (typeof candidate !== "string") {
+            continue;
+        }
+        const normalized = candidate.trim();
+        if (!normalized || seen.has(normalized)) {
+            continue;
+        }
+        seen.add(normalized);
+        keys.push(normalized);
+    }
+    return keys;
+}
+export function writeRequiredMetadata(projectRoot, projectMeta, requiredMetadata) {
+    const projectJsonPath = path.join(projectRoot, "stego-project.json");
+    const next = {
+        ...projectMeta,
+        requiredMetadata
+    };
+    try {
+        fs.writeFileSync(projectJsonPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError("WRITE_FAILURE", `Failed to update ${projectJsonPath}: ${message}`);
+    }
+}

package/dist/stego-cli/src/modules/spine/types.js

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

package/dist/stego-cli/src/modules/workspace/application/discover-projects.js

@@ -0,0 +1,18 @@
+import fs from "node:fs";
+import path from "node:path";
+export function discoverWorkspaceProjects(workspace) {
+    const projectsRoot = path.join(workspace.repoRoot, workspace.config.projectsDir);
+    if (!fs.existsSync(projectsRoot)) {
+        return [];
+    }
+    return fs.readdirSync(projectsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .filter((projectId) => fs.existsSync(path.join(projectsRoot, projectId, "stego-project.json")))
+        .sort((left, right) => left.localeCompare(right))
+        .map((projectId) => ({
+        id: projectId,
+        root: path.join(projectsRoot, projectId),
+        projectJsonPath: path.join(projectsRoot, projectId, "stego-project.json")
+    }));
+}

package/dist/stego-cli/src/modules/workspace/application/resolve-workspace.js

@@ -0,0 +1,73 @@
+import path from "node:path";
+import { CliError } from "../../../../../shared/src/contracts/cli/index.js";
+import { ROOT_CONFIG_FILENAME } from "../types.js";
+import { findNearestFileUpward, isDirectory, pathExists, readJsonFile } from "../infra/workspace-repo.js";
+export function resolveWorkspaceContext(input) {
+    if (input.rootOption) {
+        return resolveFromExplicitRoot(input.cwd, input.rootOption);
+    }
+    const discoveredConfigPath = findNearestFileUpward(input.cwd, ROOT_CONFIG_FILENAME);
+    if (!discoveredConfigPath) {
+        const legacyConfigPath = findNearestFileUpward(input.cwd, "writing.config.json");
+        if (legacyConfigPath) {
+            throw new CliError("WORKSPACE_NOT_FOUND", `Found legacy '${path.basename(legacyConfigPath)}' at '${path.dirname(legacyConfigPath)}'. Rename it to '${ROOT_CONFIG_FILENAME}'.`);
+        }
+        throw new CliError("WORKSPACE_NOT_FOUND", `No Stego workspace found from '${input.cwd}'. Run 'stego init' or pass --root <path>.`);
+    }
+    const repoRoot = path.dirname(discoveredConfigPath);
+    const config = parseWorkspaceConfig(discoveredConfigPath);
+    return {
+        repoRoot,
+        configPath: discoveredConfigPath,
+        config
+    };
+}
+function resolveFromExplicitRoot(cwd, rootOption) {
+    const explicitRoot = path.resolve(cwd, rootOption);
+    if (!pathExists(explicitRoot) || !isDirectory(explicitRoot)) {
+        throw new CliError("WORKSPACE_NOT_FOUND", `Workspace root does not exist or is not a directory: ${explicitRoot}`);
+    }
+    const explicitConfigPath = path.join(explicitRoot, ROOT_CONFIG_FILENAME);
+    if (!pathExists(explicitConfigPath)) {
+        const legacyConfigPath = path.join(explicitRoot, "writing.config.json");
+        if (pathExists(legacyConfigPath)) {
+            throw new CliError("WORKSPACE_NOT_FOUND", `Found legacy 'writing.config.json' at '${explicitRoot}'. Rename it to '${ROOT_CONFIG_FILENAME}'.`);
+        }
+        throw new CliError("WORKSPACE_NOT_FOUND", `No Stego workspace found at '${explicitRoot}'. Expected '${ROOT_CONFIG_FILENAME}'.`);
+    }
+    return {
+        repoRoot: explicitRoot,
+        configPath: explicitConfigPath,
+        config: parseWorkspaceConfig(explicitConfigPath)
+    };
+}
+function parseWorkspaceConfig(configPath) {
+    let parsed;
+    try {
+        parsed = readJsonFile(configPath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError("INVALID_CONFIGURATION", `Invalid JSON at ${configPath}: ${message}`);
+    }
+    if (!isWorkspaceConfig(parsed)) {
+        throw new CliError("INVALID_CONFIGURATION", `Invalid Stego workspace config at ${configPath}.`);
+    }
+    return parsed;
+}
+function isWorkspaceConfig(value) {
+    if (!isPlainObject(value)) {
+        return false;
+    }
+    return typeof value.projectsDir === "string"
+        && typeof value.chapterDir === "string"
+        && typeof value.spineDir === "string"
+        && typeof value.notesDir === "string"
+        && typeof value.distDir === "string"
+        && Array.isArray(value.requiredMetadata)
+        && Array.isArray(value.allowedStatuses)
+        && isPlainObject(value.stagePolicies);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/stego-cli/src/modules/workspace/commands/list-projects.js

@@ -0,0 +1,40 @@
+import { writeText } from "../../../app/output-renderer.js";
+import { discoverWorkspaceProjects } from "../application/discover-projects.js";
+import { resolveWorkspaceContext } from "../application/resolve-workspace.js";
+export function registerListProjectsCommand(registry) {
+    registry.register({
+        name: "list-projects",
+        description: "List projects in the workspace",
+        options: [
+            {
+                flags: "--root <path>",
+                description: "Workspace root path"
+            }
+        ],
+        action: (context) => {
+            const workspace = resolveWorkspaceContext({
+                cwd: context.cwd,
+                rootOption: readStringOption(context.options, "root")
+            });
+            const projects = discoverWorkspaceProjects(workspace);
+            if (projects.length === 0) {
+                writeText("No projects found.");
+                return;
+            }
+            writeText("Projects:");
+            for (const project of projects) {
+                writeText(`- ${project.id}`);
+            }
+        }
+    });
+}
+function readStringOption(options, key) {
+    const value = options[key];
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return String(value);
+    }
+    return undefined;
+}

package/dist/stego-cli/src/modules/workspace/index.js

@@ -0,0 +1,9 @@
+import { registerListProjectsCommand } from "./commands/list-projects.js";
+export const workspaceModule = {
+    registerCommands(registry) {
+        registerListProjectsCommand(registry);
+    }
+};
+export * from "./types.js";
+export * from "./application/resolve-workspace.js";
+export * from "./application/discover-projects.js";

package/dist/stego-cli/src/modules/workspace/infra/workspace-repo.js

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+export function pathExists(value) {
+    return fs.existsSync(value);
+}
+export function isDirectory(value) {
+    try {
+        return fs.statSync(value).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function readJsonFile(filePath) {
+    const raw = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(raw);
+}
+export function findNearestFileUpward(startPath, filename) {
+    let current = path.resolve(startPath);
+    if (!pathExists(current)) {
+        return null;
+    }
+    if (!isDirectory(current)) {
+        current = path.dirname(current);
+    }
+    while (true) {
+        const candidate = path.join(current, filename);
+        if (pathExists(candidate)) {
+            return candidate;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}

package/dist/stego-cli/src/modules/workspace/types.js

@@ -0,0 +1 @@
+export const ROOT_CONFIG_FILENAME = "stego.config.json";

package/dist/stego-cli/src/platform/clock.js

@@ -0,0 +1,3 @@
+export function nowIsoString() {
+    return new Date().toISOString();
+}

package/dist/stego-cli/src/platform/fs.js

@@ -0,0 +1,13 @@
+import fs from "node:fs";
+export const fileSystem = {
+    existsSync: fs.existsSync,
+    readFileSync: fs.readFileSync,
+    writeFileSync: fs.writeFileSync,
+    mkdirSync: fs.mkdirSync,
+    readdirSync: fs.readdirSync,
+    statSync: fs.statSync,
+    cpSync: fs.cpSync,
+    copyFileSync: fs.copyFileSync,
+    mkdtempSync: fs.mkdtempSync,
+    rmSync: fs.rmSync
+};

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

@@ -0,0 +1,3 @@
+export * from "./clock.js";
+export * from "./fs.js";
+export * from "./temp-files.js";

package/dist/stego-cli/src/platform/temp-files.js

@@ -0,0 +1,6 @@
+import os from "node:os";
+import path from "node:path";
+import { fileSystem } from "./fs.js";
+export function makeTempDir(prefix) {
+    return fileSystem.mkdtempSync(path.join(os.tmpdir(), prefix));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stego-cli",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "description": "Installable CLI for the Stego writing monorepo workflow.",
   "license": "Apache-2.0",
@@ -14,7 +14,7 @@
   },
   "homepage": "https://github.com/matt-gold/stego/tree/main/packages/stego-cli#readme",
   "bin": {
-    "stego": "dist/stego-cli.js"
+    "stego": "dist/stego-cli/src/main.js"
   },
   "engines": {
     "node": ">=20"
@@ -41,25 +41,34 @@
     "pack:dry-run": "npm pack --dry-run",
     "changeset": "changeset",
     "release:version": "changeset version",
-    "list-projects": "node --experimental-strip-types tools/stego-cli.ts list-projects",
-    "new-project": "node --experimental-strip-types tools/stego-cli.ts new-project",
-    "new": "node --experimental-strip-types tools/stego-cli.ts new",
-    "lint": "node --experimental-strip-types tools/stego-cli.ts lint",
-    "validate": "node --experimental-strip-types tools/stego-cli.ts validate",
-    "build": "node --experimental-strip-types tools/stego-cli.ts build",
-    "check-stage": "node --experimental-strip-types tools/stego-cli.ts check-stage",
-    "export": "node --experimental-strip-types tools/stego-cli.ts export",
+    "list-projects": "node --experimental-strip-types src/main.ts list-projects",
+    "new-project": "node --experimental-strip-types src/main.ts new-project",
+    "new": "node --experimental-strip-types src/main.ts new",
+    "lint": "node --experimental-strip-types src/main.ts lint",
+    "validate": "node --experimental-strip-types src/main.ts validate",
+    "build": "node --experimental-strip-types src/main.ts build",
+    "check-stage": "node --experimental-strip-types src/main.ts check-stage",
+    "export": "node --experimental-strip-types src/main.ts export",
     "test:compile-structure": "node --test tools/test/compile-structure.test.mjs",
     "test:comments": "node --test tools/test/comments-add.test.mjs",
+    "test:cli-core": "node --test tools/test/cli-core.test.mjs",
     "test:spine-v2": "node --test tools/test/spine-v2.test.mjs",
-    "test": "npm run test:compile-structure && npm run test:comments && npm run test:spine-v2"
+    "test:workspace-project": "node --test tools/test/workspace-project.test.mjs",
+    "test": "npm run test:compile-structure && npm run test:comments && npm run test:cli-core && npm run test:spine-v2 && npm run test:workspace-project && npm run check:module-apis && npm run check:boundaries",
+    "check:boundaries": "node scripts/check-module-boundaries.mjs",
+    "check:module-apis": "node scripts/check-module-apis.mjs"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.2.3",
     "cspell": "^9.6.4",
     "markdownlint-cli": "^0.47.0",
     "pandoc": "^0.2.0",
     "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "cac": "^7.0.0",
+    "js-yaml": "^4.1.1"
   }
 }