stego-cli 0.4.0 → 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

@@ -70,6 +70,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/stego-cli.js

@@ -25,6 +25,7 @@ const RESERVED_COMMENT_PREFIX = "CMT";
 const DEFAULT_NEW_MANUSCRIPT_SLUG = "new-document";
 const ROOT_CONFIG_FILENAME = "stego.config.json";
 const PROSE_FONT_PROMPT = "Switch workspace to proportional (prose-style) font? (recommended)";
+const COMMENT_AUTHOR_PROMPT = "Default comment author for stego.comments.author?";
 const SCAFFOLD_GITIGNORE_CONTENT = `node_modules/
 /dist/
 .DS_Store
@@ -92,6 +93,103 @@ stego new-project --project my-book --title "My Book"
 stego new --project fiction-example
 \`\`\`
 `;
+const SCAFFOLD_AGENTS_CONTENT = `# AGENTS.md
+
+## Purpose
+
+This workspace is designed to be AI-friendly for writing workflows.
+
+## Canonical CLI Interface
+
+- Run \`stego --help\` for the full command reference.
+- Run \`stego --version\` to confirm which CLI is active.
+- Run project docs commands in \`projects/stego-docs\` when available.
+
+## CLI Resolution Rules
+
+- Prefer local CLI over global CLI:
+  - \`npm exec -- stego ...\`
+  - \`npx --no-install stego ...\`
+- At the start of mutation tasks, run \`stego --version\` and report the version used.
+
+## Workspace Discovery Checklist
+
+1. Confirm workspace root contains \`stego.config.json\`.
+2. Run \`stego list-projects\`.
+3. Use explicit \`--project <id>\` for project-scoped commands.
+
+## CLI-First Policy (Required)
+
+When asked to edit Stego project content, use documented Stego CLI commands first.
+
+Typical targets:
+
+- manuscript files
+- spine categories and entries
+- frontmatter metadata
+- comments
+- stage/build/export workflows
+
+Preferred commands include:
+
+- \`stego new\`
+- \`stego spine read\`
+- \`stego spine new-category\`
+- \`stego spine new\`
+- \`stego metadata read\`
+- \`stego metadata apply\`
+- \`stego comments ...\`
+
+## Machine-Mode Output
+
+- For automation and integrations, prefer \`--format json\` and parse structured output.
+- Use text output only for human-facing summaries.
+
+## Mutation Protocol
+
+1. Read current state first (\`metadata read\`, \`spine read\`, \`comments read\`).
+2. Mutate via CLI commands.
+3. Verify after writes (\`stego validate --project <id>\` and relevant read commands).
+
+## Manual Edit Fallback
+
+Manual file edits are a last resort.
+
+If manual edits are required, the agent must:
+
+1. warn that CLI was bypassed,
+2. explain why CLI could not be used, and
+3. list which files were manually edited.
+
+## Failure Contract
+
+When CLI fails:
+
+1. show the attempted command,
+2. summarize the error briefly,
+3. report the recovery attempt, and
+4. if fallback is required, apply the Manual Edit Fallback policy.
+
+## Validation Expectations
+
+After mutations, run relevant checks when feasible (for example \`stego validate --project <id>\`) and report results.
+
+## Scope Guardrails
+
+- Do not manually edit \`dist/\` outputs or compiled export artifacts.
+- Do not modify files outside the requested project scope unless the user explicitly asks.
+
+## Task To Command Quick Map
+
+- New manuscript: \`stego new --project <id> [--filename <name>]\`
+- Read spine: \`stego spine read --project <id> --format json\`
+- New spine category: \`stego spine new-category --project <id> --key <category>\`
+- New spine entry: \`stego spine new --project <id> --category <category> [--filename <path>]\`
+- Read metadata: \`stego metadata read <markdown-path> --format json\`
+- Apply metadata: \`stego metadata apply <markdown-path> --input <path|-> --format json\`
+- Read comments: \`stego comments read <manuscript> --format json\`
+- Mutate comments: \`stego comments add|reply|set-status|delete|clear-resolved|sync-anchors ... --format json\`
+`;
 const PROSE_MARKDOWN_EDITOR_SETTINGS = {
     "[markdown]": {
         "editor.fontFamily": "Inter, Helvetica Neue, Helvetica, Arial, sans-serif",
@@ -105,7 +203,8 @@ const PROSE_MARKDOWN_EDITOR_SETTINGS = {
 };
 const PROJECT_EXTENSION_RECOMMENDATIONS = [
     "matt-gold.stego-extension",
-    "matt-gold.saurus-extension"
+    "matt-gold.saurus-extension",
+    "streetsidesoftware.code-spell-checker"
 ];
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(scriptDir, "..");
@@ -513,6 +612,7 @@ async function initWorkspace(options) {
     const copiedPaths = [];
     writeScaffoldGitignore(targetRoot, copiedPaths);
     writeScaffoldReadme(targetRoot, copiedPaths);
+    writeScaffoldAgents(targetRoot, copiedPaths);
     copyTemplateAsset(".markdownlint.json", targetRoot, copiedPaths);
     copyTemplateAsset(".markdownlint.manuscript.json", targetRoot, copiedPaths);
     copyTemplateAsset(".cspell.json", targetRoot, copiedPaths);
@@ -522,8 +622,13 @@ async function initWorkspace(options) {
     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);
+    const suggestedCommentAuthor = resolveSuggestedCommentAuthor(targetRoot);
+    const commentAuthor = (await promptText(COMMENT_AUTHOR_PROMPT, suggestedCommentAuthor)).trim();
+    if (enableProseFont || commentAuthor) {
+        writeProjectProseEditorSettings(targetRoot, copiedPaths, {
+            enableProseFont,
+            commentAuthor
+        });
     }
     writeInitRootPackageJson(targetRoot);
     logLine(`Initialized Stego workspace in ${targetRoot}`);
@@ -566,6 +671,46 @@ async function promptYesNo(question, defaultYes) {
         rl.close();
     }
 }
+async function promptText(question, defaultValue = "") {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return defaultValue;
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    const suffix = defaultValue ? ` [${defaultValue}] ` : " ";
+    try {
+        const answer = (await rl.question(`${question}${suffix}`)).trim();
+        if (!answer) {
+            return defaultValue;
+        }
+        return answer;
+    }
+    finally {
+        rl.close();
+    }
+}
+function resolveSuggestedCommentAuthor(cwd) {
+    const gitAuthor = spawnSync("git", ["config", "--get", "user.name"], {
+        cwd,
+        encoding: "utf8"
+    });
+    const fromGit = (gitAuthor.stdout || "").trim();
+    if (gitAuthor.status === 0 && fromGit) {
+        return fromGit;
+    }
+    try {
+        const username = os.userInfo().username.trim();
+        if (username) {
+            return username;
+        }
+    }
+    catch {
+        // ignore lookup failure and fall back to empty
+    }
+    return "";
+}
 function copyTemplateAsset(sourceRelativePath, targetRoot, copiedPaths, options) {
     const sourcePath = path.join(packageRoot, sourceRelativePath);
     if (!fs.existsSync(sourcePath)) {
@@ -600,6 +745,11 @@ function writeScaffoldReadme(targetRoot, copiedPaths) {
     fs.writeFileSync(destinationPath, SCAFFOLD_README_CONTENT, "utf8");
     copiedPaths.push("README.md");
 }
+function writeScaffoldAgents(targetRoot, copiedPaths) {
+    const destinationPath = path.join(targetRoot, "AGENTS.md");
+    fs.writeFileSync(destinationPath, SCAFFOLD_AGENTS_CONTENT, "utf8");
+    copiedPaths.push("AGENTS.md");
+}
 function shouldCopyTemplatePath(currentSourcePath) {
     const relativePath = path.relative(packageRoot, currentSourcePath);
     if (!relativePath || relativePath.startsWith("..")) {
@@ -675,7 +825,7 @@ function ensureProjectExtensionsRecommendations(projectRoot) {
     };
     fs.writeFileSync(extensionsPath, `${JSON.stringify(extensionsConfig, null, 2)}\n`, "utf8");
 }
-function writeProjectProseEditorSettings(targetRoot, copiedPaths) {
+function writeProjectProseEditorSettings(targetRoot, copiedPaths, options) {
     const projectsRoot = path.join(targetRoot, "projects");
     if (!fs.existsSync(projectsRoot)) {
         return;
@@ -685,14 +835,16 @@ function writeProjectProseEditorSettings(targetRoot, copiedPaths) {
             continue;
         }
         const projectRoot = path.join(projectsRoot, entry.name);
-        const settingsPath = writeProseEditorSettingsForProject(projectRoot);
+        const settingsPath = writeProseEditorSettingsForProject(projectRoot, options);
         copiedPaths.push(path.relative(targetRoot, settingsPath));
     }
 }
-function writeProseEditorSettingsForProject(projectRoot) {
+function writeProseEditorSettingsForProject(projectRoot, options) {
     const vscodeDir = path.join(projectRoot, ".vscode");
     const settingsPath = path.join(vscodeDir, "settings.json");
     fs.mkdirSync(vscodeDir, { recursive: true });
+    const enableProseFont = options?.enableProseFont ?? true;
+    const commentAuthor = (options?.commentAuthor ?? "").trim();
     let existingSettings = {};
     if (fs.existsSync(settingsPath)) {
         try {
@@ -708,17 +860,22 @@ function writeProseEditorSettingsForProject(projectRoot) {
     const proseMarkdownSettings = isPlainObject(PROSE_MARKDOWN_EDITOR_SETTINGS["[markdown]"])
         ? PROSE_MARKDOWN_EDITOR_SETTINGS["[markdown]"]
         : {};
-    const existingMarkdownSettings = isPlainObject(existingSettings["[markdown]"])
-        ? existingSettings["[markdown]"]
-        : {};
     const nextSettings = {
-        ...existingSettings,
-        "[markdown]": {
+        ...existingSettings
+    };
+    if (enableProseFont) {
+        const existingMarkdownSettings = isPlainObject(existingSettings["[markdown]"])
+            ? existingSettings["[markdown]"]
+            : {};
+        nextSettings["[markdown]"] = {
             ...existingMarkdownSettings,
             ...proseMarkdownSettings
-        },
-        "markdown.preview.fontFamily": PROSE_MARKDOWN_EDITOR_SETTINGS["markdown.preview.fontFamily"]
-    };
+        };
+        nextSettings["markdown.preview.fontFamily"] = PROSE_MARKDOWN_EDITOR_SETTINGS["markdown.preview.fontFamily"];
+    }
+    if (commentAuthor) {
+        nextSettings["stego.comments.author"] = commentAuthor;
+    }
     fs.writeFileSync(settingsPath, `${JSON.stringify(nextSettings, null, 2)}\n`, "utf8");
     return settingsPath;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stego-cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "Installable CLI for the Stego writing monorepo workflow.",
   "license": "Apache-2.0",