@cms-lab/cli 1.2.1 → 1.2.2

package/README.md

@@ -23,6 +23,7 @@ cms-lab scan --json --include-sensitive-output
 cms-lab scan --max-warnings 0
 cms-lab scan --strict
 cms-lab agent-context
+cms-lab agent-context --mode cms-only
 cms-lab agent-context --preset all
 cms-lab agent-context --preset claude
 cms-lab agent-context --preset gemini
@@ -61,7 +62,9 @@ cms-lab docs, package links, route mappings, and safe project facts before
 attempting fixes. The default preset writes `AGENTS.md` plus shared files in
 `.cms-lab/`. Tool-specific presets can write `CLAUDE.md`, `GEMINI.md`, Copilot
 instructions, and a reusable Copilot prompt. Existing files are not overwritten
-unless `--force` is passed.
+unless `--force` is passed. Use `--mode cms-only` in backend-only CMS projects;
+the generated context will state that no frontend was detected and that route
+scans need a running app.
 
 ## Config
 

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runCli
-} from "./chunk-7YUQWS4P.js";
+} from "./chunk-SVTBRARJ.js";
 
 // src/bin.ts
 var exitCode = await runCli(process.argv.slice(2));

package/dist/{chunk-7YUQWS4P.js → chunk-SVTBRARJ.js}

@@ -131,30 +131,34 @@ function renderAgentContextFiles(options) {
   if (includeAgentsMd) {
     files.push({
       path: "AGENTS.md",
-      content: renderAgentsMd(contextPath, promptPath)
+      content: renderAgentsMd(contextPath, promptPath, options.project)
     });
   }
   if (options.preset === "claude" || options.preset === "all") {
     files.push({
       path: "CLAUDE.md",
-      content: renderClaudeMd(contextPath, promptPath)
+      content: renderClaudeMd(contextPath, promptPath, options.project)
     });
   }
   if (options.preset === "gemini" || options.preset === "all") {
     files.push({
       path: "GEMINI.md",
-      content: renderGeminiMd(contextPath, promptPath)
+      content: renderGeminiMd(contextPath, promptPath, options.project)
     });
   }
   if (options.preset === "copilot" || options.preset === "all") {
     files.push(
       {
         path: ".github/copilot-instructions.md",
-        content: renderCopilotInstructions(contextPath, promptPath)
+        content: renderCopilotInstructions(
+          contextPath,
+          promptPath,
+          options.project
+        )
       },
       {
         path: ".github/prompts/cms-lab-fix.prompt.md",
-        content: renderCopilotPrompt(contextPath, promptPath)
+        content: renderCopilotPrompt(contextPath, promptPath, options.project)
       }
     );
   }
@@ -170,10 +174,10 @@ function renderAgentContextFiles(options) {
   );
   return files;
 }
-function renderAgentsMd(contextPath, promptPath) {
+function renderAgentsMd(contextPath, promptPath, project) {
   return `# cms-lab agent handoff
 
-This project uses cms-lab to check CMS content against the routes and fields the Next.js app expects.
+${agentProjectSummary(project)}
 
 Before changing code for CMS-related failures:
 
@@ -184,47 +188,47 @@ Before changing code for CMS-related failures:
    - npm: ${NPM_URL}
    - Docs: ${DOCS_URL}
 4. Run \`npx @cms-lab/cli doctor\` before a first scan.
-5. Run \`npx @cms-lab/cli scan --ci --report\` to reproduce diagnostics.
+5. ${agentScanInstruction(project)}
 6. Use \`npx @cms-lab/cli explain <CODE>\` for diagnostic details.
 
 Do not print or commit CMS tokens, webhook URLs, private site URLs, raw CMS payloads, or local absolute paths.
 `;
 }
-function renderClaudeMd(contextPath, promptPath) {
+function renderClaudeMd(contextPath, promptPath, project) {
   return `# cms-lab Claude Code context
 
 @${contextPath}
 @${promptPath}
 
-Use these cms-lab files before changing code for CMS route, field, SEO, or report diagnostics. Run \`npx @cms-lab/cli doctor\` first when connecting a project, then run \`npx @cms-lab/cli scan --ci --report\` to reproduce the current diagnostics.
+Use these cms-lab files before changing code for CMS route, field, SEO, or report diagnostics. ${toolScanGuidance(project)}
 
 Do not print or commit CMS tokens, webhook URLs, private site URLs, raw CMS payloads, or local absolute paths.
 `;
 }
-function renderGeminiMd(contextPath, promptPath) {
+function renderGeminiMd(contextPath, promptPath, project) {
   return `# cms-lab Gemini CLI context
 
 @${contextPath}
 @${promptPath}
 
-Use these cms-lab files before changing code for CMS route, field, SEO, or report diagnostics. Run \`npx @cms-lab/cli doctor\` first when connecting a project, then run \`npx @cms-lab/cli scan --ci --report\` to reproduce the current diagnostics.
+Use these cms-lab files before changing code for CMS route, field, SEO, or report diagnostics. ${toolScanGuidance(project)}
 
 Do not print or commit CMS tokens, webhook URLs, private site URLs, raw CMS payloads, or local absolute paths.
 `;
 }
-function renderCopilotInstructions(contextPath, promptPath) {
+function renderCopilotInstructions(contextPath, promptPath, project) {
   return `# cms-lab Copilot instructions
 
-This project uses cms-lab to check CMS content against the routes and fields the Next.js app expects.
+${agentProjectSummary(project)}
 
 - Read \`${contextPath}\` before changing code for CMS diagnostics.
 - Use \`${promptPath}\` when asked to investigate a cms-lab failure.
-- Prefer reproducing with \`npx @cms-lab/cli scan --ci --report\` before editing application code.
+- ${toolScanBullet(project)}
 - Use \`npx @cms-lab/cli explain <CODE>\` before deciding where a diagnostic should be fixed.
 - Do not print or commit CMS tokens, webhook URLs, private site URLs, raw CMS payloads, or local absolute paths.
 `;
 }
-function renderCopilotPrompt(contextPath, promptPath) {
+function renderCopilotPrompt(contextPath, promptPath, project) {
   return `# Fix cms-lab diagnostics
 
 Use this prompt when investigating cms-lab diagnostics in this repository.
@@ -232,7 +236,7 @@ Use this prompt when investigating cms-lab diagnostics in this repository.
 1. Read \`${contextPath}\`.
 2. Read \`${promptPath}\`.
 3. Run \`npx @cms-lab/cli doctor\`.
-4. Run \`npx @cms-lab/cli scan --ci --report\`.
+4. ${toolPromptScanStep(project)}
 5. For each diagnostic code, run \`npx @cms-lab/cli explain <CODE>\`.
 6. Decide whether the fix belongs in CMS content, cms-lab route mapping, or application code.
 7. Make the smallest verifiable change and rerun cms-lab.
@@ -254,7 +258,7 @@ Use this file to orient coding agents before they work on CMS route, field, SEO,
 ## Project scan model
 
 - Config file: ${options.configFile}
-- Framework: ${projectLabel(options.project)}
+${projectFact(options.project)}
 - CMS provider: ${options.config.cms.provider}
 - Site URL: configured in cms-lab config (redacted)
 
@@ -272,11 +276,13 @@ ${checksSummary(options.config)}
 
 \`\`\`sh
 npx @cms-lab/cli doctor
-npx @cms-lab/cli scan --ci --report
+${options.project ? "npx @cms-lab/cli scan --ci --report" : "# Add or start the frontend before running route scans"}
 npx @cms-lab/cli scan --json
 npx @cms-lab/cli explain CMS-ROUTE-404
 \`\`\`
 
+${options.project ? "" : "Route scans require a running frontend. Use this context to document the CMS shape now, then add route mappings and scan commands once the frontend exists.\n"}
+
 ## Agent workflow
 
 - Read the cms-lab config and this context before editing application code.
@@ -289,7 +295,7 @@ npx @cms-lab/cli explain CMS-ROUTE-404
 function renderPromptFile(options) {
   return `# cms-lab agent prompt
 
-You are working in a Next.js project that uses cms-lab to catch CMS-driven failures before deploy.
+${promptProjectSummary(options.project)}
 
 This prompt is suitable for agents such as Claude Code, Codex, Gemini CLI, Antigravity, OpenCode, and similar coding agents.
 
@@ -308,10 +314,12 @@ npx @cms-lab/cli scan --ci --report
 
 Project facts:
 
-- Framework: ${projectLabel(options.project)}
+${projectFact(options.project)}
 - CMS provider: ${options.config.cms.provider}
 - Route mappings: ${options.config.routes.map((route) => `${route.type} -> ${route.pattern}`).join(", ")}
 
+${options.project ? "" : "Add frontend route config before running route scans. The frontend has not been detected yet, so use this context for CMS schema, collection, and route-planning work first.\n"}
+
 When diagnostics appear, use \`npx @cms-lab/cli explain <CODE>\` before deciding whether the fix belongs in CMS content, route mapping, or application code.
 
 Never reveal CMS tokens, private site URLs, webhook URLs, raw CMS payloads, or local absolute paths in commits, issues, pull requests, logs, or summaries.
@@ -399,6 +407,48 @@ function projectLabel(project) {
   }
   return `${project.framework} ${project.router}`;
 }
+function projectFact(project) {
+  if (!project) {
+    return "- Frontend: not detected";
+  }
+  return `- Framework: ${projectLabel(project)}`;
+}
+function agentProjectSummary(project) {
+  if (!project) {
+    return "This project uses cms-lab to describe CMS content expectations before a frontend has been detected.";
+  }
+  return "This project uses cms-lab to check CMS content against the routes and fields the Next.js app expects.";
+}
+function agentScanInstruction(project) {
+  if (!project) {
+    return "Add or start the frontend before running route scans.";
+  }
+  return "Run `npx @cms-lab/cli scan --ci --report` to reproduce diagnostics.";
+}
+function promptProjectSummary(project) {
+  if (!project) {
+    return "You are working in a CMS/backend project where the frontend has not been detected yet. Use cms-lab to document the CMS shape and prepare route checks before deploy.";
+  }
+  return "You are working in a Next.js project that uses cms-lab to catch CMS-driven failures before deploy.";
+}
+function toolScanGuidance(project) {
+  if (!project) {
+    return "The frontend has not been detected yet; run `npx @cms-lab/cli doctor` for config checks and add or start the frontend before route scans.";
+  }
+  return "Run `npx @cms-lab/cli doctor` first when connecting a project, then run `npx @cms-lab/cli scan --ci --report` to reproduce the current diagnostics.";
+}
+function toolScanBullet(project) {
+  if (!project) {
+    return "The frontend has not been detected yet; use the context for CMS setup work and add or start the frontend before route scans.";
+  }
+  return "Prefer reproducing with `npx @cms-lab/cli scan --ci --report` before editing application code.";
+}
+function toolPromptScanStep(project) {
+  if (!project) {
+    return "The frontend has not been detected yet; add or start it before running `npx @cms-lab/cli scan --ci --report`.";
+  }
+  return "Run `npx @cms-lab/cli scan --ci --report`.";
+}
 function trimSlashes(value) {
   let start = 0;
   let end = value.length;
@@ -515,7 +565,7 @@ var noColor = {
 // src/index.ts
 async function runCli(argv, dependencies = {}) {
   let exitCode = 0;
-  const program = new Command().name("cms-lab").description("Catch CMS bugs before deploy.").version("1.2.1").exitOverride().configureOutput({
+  const program = new Command().name("cms-lab").description("Catch CMS bugs before deploy.").version("1.2.2").exitOverride().configureOutput({
     writeOut: (text) => writeStdout(dependencies, text),
     writeErr: (text) => writeStderr(dependencies, text)
   });
@@ -634,7 +684,7 @@ Examples:
   ).action(async (options) => {
     exitCode = await runInit(options, dependencies);
   });
-  program.command("agent-context").description("Generate AI-agent handoff files for cms-lab projects.").option("--config <path>", "Path to cms-lab config file").option(
+  program.command("agent-context").description("Generate AI-agent handoff files for cms-lab projects.").option("--config <path>", "Path to cms-lab config file").option("--mode <mode>", "Project mode: auto, next, or cms-only", "auto").option(
     "--out <dir>",
     "Directory for generated cms-lab agent files",
     ".cms-lab"
@@ -648,6 +698,7 @@ Examples:
 Examples:
   cms-lab agent-context
   cms-lab agent-context --config cms-lab.config.ts
+  cms-lab agent-context --mode cms-only
   cms-lab agent-context --preset all
   cms-lab agent-context --preset claude
   cms-lab agent-context --preset copilot
@@ -1003,12 +1054,20 @@ async function runInit(options, dependencies) {
 async function runAgentContext(options, dependencies) {
   const cwd = dependencies.cwd ?? process.cwd();
   try {
+    const mode = parseAgentContextMode(options.mode);
     const loaded = await loadCmsLabConfig({ cwd, configPath: options.config });
-    const project = await detectNextProject(cwd);
-    assertConfiguredRouterMatchesProject(
-      loaded.config.framework.router,
-      project
-    );
+    const project = mode === "cms-only" ? void 0 : await detectOptionalNextProject(cwd, mode);
+    if (project) {
+      assertConfiguredRouterMatchesProject(
+        loaded.config.framework.router,
+        project
+      );
+    } else {
+      writeStdout(
+        dependencies,
+        "No Next.js project detected; generating CMS-only agent context.\n"
+      );
+    }
     const files = renderAgentContextFiles({
       config: loaded.config,
       project,
@@ -1059,6 +1118,23 @@ async function runAgentContext(options, dependencies) {
     return 2;
   }
 }
+function parseAgentContextMode(value) {
+  const mode = value ?? "auto";
+  if (mode === "auto" || mode === "next" || mode === "cms-only") {
+    return mode;
+  }
+  throw new ConfigLoadError("--mode must be one of: auto, next, cms-only");
+}
+async function detectOptionalNextProject(cwd, mode) {
+  try {
+    return await detectNextProject(cwd);
+  } catch (error) {
+    if (mode === "next" || !(error instanceof ConfigLoadError)) {
+      throw error;
+    }
+    return void 0;
+  }
+}
 function writeStdout(dependencies, text) {
   if (dependencies.stdout) {
     dependencies.stdout(text);

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   runCli
-} from "./chunk-7YUQWS4P.js";
+} from "./chunk-SVTBRARJ.js";
 export {
   runCli
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cms-lab/cli",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "type": "module",
   "description": "Catch CMS bugs before deploy.",
   "license": "MIT",
@@ -47,15 +47,15 @@
   "dependencies": {
     "commander": "^14.0.2",
     "picocolors": "^1.1.1",
-    "@cms-lab/directus": "1.2.1",
-    "@cms-lab/next": "1.2.1",
-    "@cms-lab/contentful": "1.2.1",
-    "@cms-lab/prismic": "1.2.1",
-    "@cms-lab/core": "1.2.1",
-    "@cms-lab/reporter": "1.2.1",
-    "@cms-lab/wordpress": "1.2.1",
-    "@cms-lab/strapi": "1.2.1",
-    "@cms-lab/sanity": "1.2.1"
+    "@cms-lab/contentful": "1.2.2",
+    "@cms-lab/directus": "1.2.2",
+    "@cms-lab/next": "1.2.2",
+    "@cms-lab/core": "1.2.2",
+    "@cms-lab/reporter": "1.2.2",
+    "@cms-lab/prismic": "1.2.2",
+    "@cms-lab/sanity": "1.2.2",
+    "@cms-lab/strapi": "1.2.2",
+    "@cms-lab/wordpress": "1.2.2"
   },
   "author": "Afaq Rashid",
   "scripts": {