stego-cli 0.1.2 → 0.1.4

package/README.md

@@ -1,9 +1,12 @@
 # Stego
 
-This workspace is a Markdown-first creative writing pipeline for short stories through novels.
+Stego is a Markdown-first creative writing workflow packaged as an installable CLI: `stego-cli`.
+
+This repository is the source for the CLI and the example/template content that `stego init` scaffolds into a new workspace.
 
 ## What this includes
 
+- Installable CLI (`stego`) for creating and operating Stego workspaces
 - Project-per-folder structure inside one monorepo.
 - Flexible manuscript files with per-project metadata requirements.
 - Configurable manuscript grouping via `compileStructure.levels` (for example `part` + `chapter`).
@@ -11,23 +14,77 @@ This workspace is a Markdown-first creative writing pipeline for short stories t
 - Deterministic build into one manuscript Markdown file.
 - Stage-based quality gates (`draft` -> `final`).
 - Export abstraction (`md` always, `docx`/`pdf` via optional `pandoc`).
-- TypeScript-based tooling executed directly by Node (`--experimental-strip-types`).
+- Example/demo projects (`docs-demo`, `plague-demo`) included in `stego init`.
 
-## Quick start
+## Getting started (from npm)
 
 ```bash
-cd ~/Code/stego
+npm install -g stego-cli
+
+mkdir my-stego-workspace
+cd my-stego-workspace
+stego init
+
+npm install
 npm run list-projects
-npm run new-project -- --project my-new-project --title "My New Project"
 npm run validate -- --project plague-demo
 npm run build -- --project plague-demo
 npm run check-stage -- --project plague-demo --stage revise
 npm run export -- --project plague-demo --format md
 ```
 
-`npm run new-project` scaffolds `manuscript/`, `spine/`, `notes/`, and `dist/`, and seeds `stego-project.json` with a default `characters` category plus `spine/characters.md`.
-It also creates `projects/<project-id>/.vscode/settings.json` so markdown font settings apply when opening the project folder directly.
-It also creates a project-local `package.json` so you can run `npm run validate`, `npm run build`, etc. from inside that project directory without `--project`.
+`stego init` scaffolds a new workspace in the current directory (it must be empty unless you pass `--force`).
+
+Create another project in the workspace:
+
+```bash
+stego new-project --project my-new-project --title "My New Project"
+```
+
+`stego new-project` scaffolds `manuscript/`, `spine/`, `notes/`, and `dist/`, seeds `stego-project.json`, creates a project-local `package.json`, and writes `.vscode/extensions.json` recommendations (Stego + Saurus) for that project.
+
+## Running commands for a specific project
+
+From the workspace root, target a project with `--project`:
+
+```bash
+npm run validate -- --project plague-demo
+npm run build -- --project plague-demo
+npm run check-stage -- --project plague-demo --stage proof
+npm run export -- --project plague-demo --format md
+```
+
+Each project also has local scripts, so you can work from inside the project directory:
+
+```bash
+cd projects/plague-demo
+npm run validate
+npm run build
+npm run check-stage -- --stage proof
+npm run export -- --format md
+```
+
+## VS Code workflow
+
+When you are actively working on one project, open that project directory directly in VS Code (for example `projects/plague-demo`) rather than the whole workspace.
+
+This keeps editor context focused and applies the project's recommended extensions via `projects/<project-id>/.vscode/extensions.json`.
+
+## Developing `stego-cli` (this repo)
+
+If you are working on the CLI itself (this repository), use the local development scripts:
+
+```bash
+npm install
+npm run list-projects
+npm run validate -- --project docs-demo
+npm run build -- --project plague-demo
+npm run test:compile-structure
+npm run build:cli
+npm run pack:dry-run
+```
+
+These source-repo scripts run the TypeScript CLI directly with Node (`--experimental-strip-types`) for local development.
 
 ## Export requirements (DOCX/PDF)
 
@@ -63,14 +120,22 @@ npm run export -- --project plague-demo --format docx
 npm run export -- --project plague-demo --format pdf
 ```
 
-## Project layout
+## Scaffolded workspace layout
 
 - `projects/<project-id>/manuscript/` source manuscript files
 - `projects/<project-id>/spine/` canonical spine category files (`spineCategories[*].notesFile`)
 - `projects/<project-id>/notes/` regular notes and planning docs
 - `projects/<project-id>/dist/` generated outputs only
+- `stego.config.json` workspace configuration
 - `docs/` workflow and conventions
-- `tools/` build, checks, export CLI
+- `.vscode/tasks.json` root VS Code tasks for common Stego commands
+
+## This repo layout (`stego-cli` source)
+
+- `tools/` CLI source code and exporters
+- `projects/` template/demo projects bundled by `stego init`
+- `docs/` user-facing docs copied into scaffolded workspaces
+- `.github/workflows/` CI + Changesets release automation
 
 ## Project spine categories
 

package/dist/stego-cli.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { markdownExporter } from "./exporters/markdown-exporter.js";
 import { createPandocExporter } from "./exporters/pandoc-exporter.js";
@@ -16,6 +17,7 @@ const STATUS_RANK = {
 };
 const RESERVED_COMMENT_PREFIX = "CMT";
 const ROOT_CONFIG_FILENAME = "stego.config.json";
+const PROSE_FONT_PROMPT = "Switch workspace to proportional (prose-style) font? (recommended)";
 const SCAFFOLD_GITIGNORE_CONTENT = `node_modules/
 /dist/
 .DS_Store
@@ -25,6 +27,67 @@ projects/*/dist/*
 projects/*/.vscode/settings.json
 .vscode/settings.json
 `;
+const SCAFFOLD_README_CONTENT = `# Stego Workspace
+
+This directory is a Stego writing workspace (a monorepo for one or more writing projects).
+
+## What was scaffolded
+
+- \`stego.config.json\` workspace configuration
+- \`projects/\` demo projects (\`docs-demo\` and \`plague-demo\`)
+- \`docs/\` workflow and conventions docs
+- root \`package.json\` scripts for Stego commands
+- root \`.vscode/tasks.json\` tasks for common workflows
+
+## First run
+
+\`\`\`bash
+npm install
+npm run list-projects
+\`\`\`
+
+## Run commands for a specific project (from workspace root)
+
+\`\`\`bash
+npm run validate -- --project plague-demo
+npm run build -- --project plague-demo
+npm run check-stage -- --project plague-demo --stage revise
+npm run export -- --project plague-demo --format md
+\`\`\`
+
+## Work inside one project
+
+Each project also has local scripts, so you can run commands from inside a project directory:
+
+\`\`\`bash
+cd projects/plague-demo
+npm run validate
+npm run build
+\`\`\`
+
+## VS Code recommendation
+
+When you are actively working on one project, open that project directory directly in VS Code (for example \`projects/plague-demo\`).
+
+This keeps your editor context focused and applies the project's recommended extensions (including Stego + Saurus) for that project.
+
+## Create a new project
+
+\`\`\`bash
+stego new-project --project my-book --title "My Book"
+\`\`\`
+`;
+const PROSE_MARKDOWN_EDITOR_SETTINGS = {
+    "[markdown]": {
+        "editor.fontFamily": "Inter, Helvetica Neue, Helvetica, Arial, sans-serif",
+        "editor.fontSize": 17,
+        "editor.lineHeight": 28,
+        "editor.wordWrap": "wordWrapColumn",
+        "editor.wordWrapColumn": 72,
+        "editor.lineNumbers": "off"
+    },
+    "markdown.preview.fontFamily": "Inter, Helvetica Neue, Helvetica, Arial, sans-serif"
+};
 const PROJECT_EXTENSION_RECOMMENDATIONS = [
     "matt-gold.stego-extension",
     "matt-gold.saurus-extension"
@@ -33,8 +96,8 @@ const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(scriptDir, "..");
 let repoRoot = "";
 let config;
-main();
-function main() {
+void main();
+async function main() {
     const { command, options } = parseArgs(process.argv.slice(2));
     if (!command || command === "help" || command === "--help" || command === "-h") {
         printUsage();
@@ -43,7 +106,7 @@ function main() {
     try {
         switch (command) {
             case "init":
-                initWorkspace({ force: readBooleanOption(options, "force") });
+                await initWorkspace({ force: readBooleanOption(options, "force") });
                 return;
             case "list-projects":
                 activateWorkspace(options);
@@ -51,7 +114,7 @@ function main() {
                 return;
             case "new-project":
                 activateWorkspace(options);
-                createProject(readStringOption(options, "project"), readStringOption(options, "title"));
+                await createProject(readStringOption(options, "project"), readStringOption(options, "title"));
                 return;
             case "validate": {
                 activateWorkspace(options);
@@ -388,7 +451,7 @@ function findNearestFileUpward(startPath, filename) {
         current = parent;
     }
 }
-function initWorkspace(options) {
+async function initWorkspace(options) {
     const targetRoot = process.cwd();
     const entries = fs
         .readdirSync(targetRoot, { withFileTypes: true })
@@ -398,6 +461,7 @@ function initWorkspace(options) {
     }
     const copiedPaths = [];
     writeScaffoldGitignore(targetRoot, copiedPaths);
+    writeScaffoldReadme(targetRoot, copiedPaths);
     copyTemplateAsset(".markdownlint.json", targetRoot, copiedPaths);
     copyTemplateAsset(".cspell.json", targetRoot, copiedPaths);
     copyTemplateAsset(ROOT_CONFIG_FILENAME, targetRoot, copiedPaths);
@@ -406,6 +470,10 @@ function initWorkspace(options) {
     copyTemplateAsset(path.join(".vscode", "tasks.json"), targetRoot, copiedPaths);
     copyTemplateAsset(path.join(".vscode", "extensions.json"), targetRoot, copiedPaths, { optional: true });
     rewriteTemplateProjectPackageScripts(targetRoot);
+    const enableProseFont = await promptYesNo(PROSE_FONT_PROMPT, true);
+    if (enableProseFont) {
+        writeProjectProseEditorSettings(targetRoot, copiedPaths);
+    }
     writeInitRootPackageJson(targetRoot);
     logLine(`Initialized Stego workspace in ${targetRoot}`);
     for (const relativePath of copiedPaths) {
@@ -418,6 +486,34 @@ function initWorkspace(options) {
     logLine("  npm run list-projects");
     logLine("  npm run validate -- --project plague-demo");
 }
+async function promptYesNo(question, defaultYes) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return defaultYes;
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    const suffix = defaultYes ? " [Y/n] " : " [y/N] ";
+    try {
+        while (true) {
+            const answer = (await rl.question(`${question}${suffix}`)).trim().toLowerCase();
+            if (!answer) {
+                return defaultYes;
+            }
+            if (answer === "y" || answer === "yes") {
+                return true;
+            }
+            if (answer === "n" || answer === "no") {
+                return false;
+            }
+            console.log("Please answer y or n.");
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
 function copyTemplateAsset(sourceRelativePath, targetRoot, copiedPaths, options) {
     const sourcePath = path.join(packageRoot, sourceRelativePath);
     if (!fs.existsSync(sourcePath)) {
@@ -447,6 +543,11 @@ function writeScaffoldGitignore(targetRoot, copiedPaths) {
     fs.writeFileSync(destinationPath, SCAFFOLD_GITIGNORE_CONTENT, "utf8");
     copiedPaths.push(".gitignore");
 }
+function writeScaffoldReadme(targetRoot, copiedPaths) {
+    const destinationPath = path.join(targetRoot, "README.md");
+    fs.writeFileSync(destinationPath, SCAFFOLD_README_CONTENT, "utf8");
+    copiedPaths.push("README.md");
+}
 function shouldCopyTemplatePath(currentSourcePath) {
     const relativePath = path.relative(packageRoot, currentSourcePath);
     if (!relativePath || relativePath.startsWith("..")) {
@@ -524,6 +625,53 @@ function ensureProjectExtensionsRecommendations(projectRoot) {
     };
     fs.writeFileSync(extensionsPath, `${JSON.stringify(extensionsConfig, null, 2)}\n`, "utf8");
 }
+function writeProjectProseEditorSettings(targetRoot, copiedPaths) {
+    const projectsRoot = path.join(targetRoot, "projects");
+    if (!fs.existsSync(projectsRoot)) {
+        return;
+    }
+    for (const entry of fs.readdirSync(projectsRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const projectRoot = path.join(projectsRoot, entry.name);
+        const settingsPath = writeProseEditorSettingsForProject(projectRoot);
+        copiedPaths.push(path.relative(targetRoot, settingsPath));
+    }
+}
+function writeProseEditorSettingsForProject(projectRoot) {
+    const vscodeDir = path.join(projectRoot, ".vscode");
+    const settingsPath = path.join(vscodeDir, "settings.json");
+    fs.mkdirSync(vscodeDir, { recursive: true });
+    let existingSettings = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            const parsed = readJson(settingsPath);
+            if (isPlainObject(parsed)) {
+                existingSettings = parsed;
+            }
+        }
+        catch {
+            existingSettings = {};
+        }
+    }
+    const proseMarkdownSettings = isPlainObject(PROSE_MARKDOWN_EDITOR_SETTINGS["[markdown]"])
+        ? PROSE_MARKDOWN_EDITOR_SETTINGS["[markdown]"]
+        : {};
+    const existingMarkdownSettings = isPlainObject(existingSettings["[markdown]"])
+        ? existingSettings["[markdown]"]
+        : {};
+    const nextSettings = {
+        ...existingSettings,
+        "[markdown]": {
+            ...existingMarkdownSettings,
+            ...proseMarkdownSettings
+        },
+        "markdown.preview.fontFamily": PROSE_MARKDOWN_EDITOR_SETTINGS["markdown.preview.fontFamily"]
+    };
+    fs.writeFileSync(settingsPath, `${JSON.stringify(nextSettings, null, 2)}\n`, "utf8");
+    return settingsPath;
+}
 function writeInitRootPackageJson(targetRoot) {
     const cliPackage = readJson(path.join(packageRoot, "package.json"));
     const cliVersion = typeof cliPackage.version === "string" ? cliPackage.version : "0.1.0";
@@ -565,7 +713,7 @@ function listProjects() {
         console.log(`- ${id}`);
     }
 }
-function createProject(projectIdOption, titleOption) {
+async function createProject(projectIdOption, titleOption) {
     const projectId = (projectIdOption || "").trim();
     if (!projectId) {
         throw new Error("Project id is required. Use --project <project-id>.");
@@ -625,11 +773,19 @@ function createProject(projectIdOption, titleOption) {
     fs.writeFileSync(charactersNotesPath, "# Characters\n\n", "utf8");
     const projectExtensionsPath = path.join(projectRoot, ".vscode", "extensions.json");
     ensureProjectExtensionsRecommendations(projectRoot);
+    let projectSettingsPath = null;
+    const enableProseFont = await promptYesNo(PROSE_FONT_PROMPT, true);
+    if (enableProseFont) {
+        projectSettingsPath = writeProseEditorSettingsForProject(projectRoot);
+    }
     logLine(`Created project: ${path.relative(repoRoot, projectRoot)}`);
     logLine(`- ${path.relative(repoRoot, projectJsonPath)}`);
     logLine(`- ${path.relative(repoRoot, projectPackagePath)}`);
     logLine(`- ${path.relative(repoRoot, charactersNotesPath)}`);
     logLine(`- ${path.relative(repoRoot, projectExtensionsPath)}`);
+    if (projectSettingsPath) {
+        logLine(`- ${path.relative(repoRoot, projectSettingsPath)}`);
+    }
 }
 function getProjectIds() {
     const projectsDir = path.join(repoRoot, config.projectsDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stego-cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "description": "Installable CLI for the Stego writing monorepo workflow.",
   "bin": {