next-content-overlay 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 ReadyAF
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,110 @@
+# next-content-overlay
+
+**Edit your Next.js text content from the CLI — no database, no re-prompting your AI.**
+
+If you're a vibe coder or AI-first builder, you know the pain: your app's text lives scattered across dozens of components, and every copy change means either digging into database tables or writing another natural language prompt and hoping the AI touches the right file. Multiply that by 50+ pages of real content and it becomes unmanageable.
+
+`next-content-overlay` gives you a Squarespace-style content layer for Next.js App Router projects — except it's file-backed, CLI-driven, and works with your existing codebase. No CMS platform, no vendor lock-in, no config hell.
+
+### The flow
+
+```
+init → scan → edit → publish
+```
+
+1. **Scan** your JSX and automatically detect every text string
+2. **Edit** any string by its generated key — one command, instant draft
+3. **Publish** when you're ready — drafts stay separate until you say go
+
+Your content lives in a simple JSON file. Your source code stays untouched. Version control handles the rest.
+
+### Why this exists
+
+When your app has real, comprehensive text content — frameworks, guides, course material, marketing copy — you need a way to iterate on words without re-entering your code editor or AI chat every time. This tool lets you treat content as a first-class, editable layer on top of your Next.js app.
+
+## Install
+
+```bash
+npm i -D next-content-overlay
+```
+
+## Quickstart
+
+Run from your Next.js repo root:
+
+```bash
+npx content-overlay init
+npx content-overlay scan
+npx content-overlay edit app.page.your-key "Your updated text"
+npx content-overlay publish
+```
+
+Use a key from `.overlay-content/content-map.json` for the `edit` command.
+
+## Commands
+
+```bash
+content-overlay init [--force]    # Create config + content files
+content-overlay scan              # Scan JSX for text strings
+content-overlay edit <key> <val>  # Update a draft value
+content-overlay publish           # Promote drafts to published content
+content-overlay --help
+content-overlay --version
+```
+
+## Generated files
+
+| File | Purpose |
+|------|---------|
+| `content-overlay.config.json` | Scan dirs, extensions, file paths |
+| `content/site.json` | Published content (your app reads this) |
+| `.overlay-content/content-map.json` | Auto-generated key → source mapping |
+| `.overlay-content/draft.json` | Working drafts before publish |
+| `.overlay-content/last-publish.json` | Publish metadata |
+
+## 5-minute demo
+
+A runnable Next.js demo app is included:
+
+```bash
+cd examples/next-demo
+npm install
+npm run overlay:flow
+npm run dev
+```
+
+Then open `http://localhost:3000` to see content loaded from the overlay.
+
+## How it works with AI coding
+
+If you're building with Cursor, Claude Code, Copilot, or any AI assistant:
+
+1. Let your AI scaffold components with placeholder text as usual
+2. Run `content-overlay scan` to extract all text into a structured map
+3. Edit content independently — no need to prompt your AI for every word change
+4. Your AI keeps building features; you keep refining copy in parallel
+
+This separates the "build" loop from the "write" loop, so neither blocks the other.
+
+## Local development
+
+```bash
+npm install
+npm run check
+```
+
+`npm run check` runs typecheck, tests, build, and license check.
+
+## Show your setup
+
+If you're using `next-content-overlay` in a project, we'd love to see it in action. Record a short screen capture of your workflow and share it in [Show & Tell Discussions](../../discussions/categories/show-and-tell).
+
+Standout demos may be featured in this README.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/index.cjs

@@ -0,0 +1,555 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/commands/edit.ts
+var import_node_path3 = __toESM(require("path"), 1);
+
+// src/lib/config.ts
+var import_node_path2 = __toESM(require("path"), 1);
+
+// src/lib/errors.ts
+var CliError = class extends Error {
+  code;
+  hint;
+  constructor(message, options) {
+    super(message);
+    this.name = "CliError";
+    this.code = options?.code ?? "CLI_ERROR";
+    this.hint = options?.hint;
+  }
+};
+function toErrorMessage(error) {
+  if (error instanceof CliError) {
+    return { message: error.message, hint: error.hint };
+  }
+  if (error instanceof Error) {
+    return { message: error.message };
+  }
+  return { message: String(error) };
+}
+
+// src/lib/fs.ts
+var import_node_fs = require("fs");
+var import_node_path = __toESM(require("path"), 1);
+async function ensureDir(dirPath) {
+  await import_node_fs.promises.mkdir(dirPath, { recursive: true });
+}
+async function fileExists(filePath) {
+  try {
+    await import_node_fs.promises.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readJsonFile(filePath) {
+  if (!await fileExists(filePath)) {
+    return null;
+  }
+  let raw;
+  try {
+    raw = await import_node_fs.promises.readFile(filePath, "utf8");
+  } catch {
+    throw new CliError(`Failed to read file: ${filePath}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new CliError(`Invalid JSON in file: ${filePath}`);
+  }
+}
+async function writeJsonFile(filePath, value) {
+  const dir = import_node_path.default.dirname(filePath);
+  try {
+    await ensureDir(dir);
+    await import_node_fs.promises.writeFile(filePath, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+  } catch {
+    throw new CliError(`Failed to write file: ${filePath}`);
+  }
+}
+async function collectFiles(rootDir, extensions) {
+  const files = [];
+  async function walk(currentDir) {
+    let entries;
+    try {
+      entries = await import_node_fs.promises.readdir(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = import_node_path.default.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".next" || entry.name === ".git") {
+          continue;
+        }
+        await walk(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      const ext = import_node_path.default.extname(entry.name).toLowerCase();
+      if (extensions.has(ext)) {
+        files.push(fullPath);
+      }
+    }
+  }
+  await walk(rootDir);
+  return files;
+}
+
+// src/lib/validation.ts
+function isPlainObject(input) {
+  return typeof input === "object" && input !== null && !Array.isArray(input);
+}
+function assertStringArray(input, fieldName) {
+  if (!Array.isArray(input) || input.some((value) => typeof value !== "string" || value.trim().length === 0)) {
+    throw new CliError(`Invalid ${fieldName} in content-overlay config.`, {
+      hint: `Expected "${fieldName}" to be a non-empty string array.`
+    });
+  }
+  return input;
+}
+function validateOverlayConfig(input) {
+  if (!isPlainObject(input)) {
+    throw new CliError("Invalid content-overlay config file.", {
+      hint: "Run: content-overlay init --force"
+    });
+  }
+  const version = input.version;
+  if (version !== 1) {
+    throw new CliError(`Unsupported config version: ${String(version)}.`, {
+      hint: "Run: content-overlay init --force"
+    });
+  }
+  const scanDirs = assertStringArray(input.scanDirs, "scanDirs");
+  const extensions = assertStringArray(input.extensions, "extensions");
+  const contentFile = input.contentFile;
+  const mapFile = input.mapFile;
+  const draftFile = input.draftFile;
+  if (typeof contentFile !== "string" || contentFile.trim().length === 0) {
+    throw new CliError("Invalid contentFile in content-overlay config.");
+  }
+  if (typeof mapFile !== "string" || mapFile.trim().length === 0) {
+    throw new CliError("Invalid mapFile in content-overlay config.");
+  }
+  if (typeof draftFile !== "string" || draftFile.trim().length === 0) {
+    throw new CliError("Invalid draftFile in content-overlay config.");
+  }
+  return {
+    version: 1,
+    scanDirs,
+    extensions,
+    contentFile,
+    mapFile,
+    draftFile
+  };
+}
+function ensureStringRecord(input, label) {
+  if (!isPlainObject(input)) {
+    throw new CliError(`Invalid ${label}; expected a JSON object.`, {
+      hint: "Run: content-overlay init"
+    });
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (typeof value !== "string") {
+      throw new CliError(`Invalid ${label}; key "${key}" must be a string.`);
+    }
+    result[key] = value;
+  }
+  return result;
+}
+function ensureContentMap(input) {
+  if (!Array.isArray(input)) {
+    throw new CliError("Invalid content map; expected an array.", {
+      hint: "Run: content-overlay scan"
+    });
+  }
+  const result = [];
+  for (const value of input) {
+    if (!isPlainObject(value)) {
+      throw new CliError("Invalid content map entry; expected object values.");
+    }
+    const { key, sourceFile, line, column, defaultValue } = value;
+    if (typeof key !== "string" || typeof sourceFile !== "string" || typeof line !== "number" || typeof column !== "number" || typeof defaultValue !== "string") {
+      throw new CliError("Invalid content map entry shape.", {
+        hint: "Run: content-overlay scan"
+      });
+    }
+    result.push({ key, sourceFile, line, column, defaultValue });
+  }
+  return result;
+}
+
+// src/lib/config.ts
+var CONFIG_FILE = "content-overlay.config.json";
+var DEFAULT_CONFIG = {
+  version: 1,
+  scanDirs: ["app", "components"],
+  extensions: [".tsx", ".ts", ".jsx", ".js", ".mdx"],
+  contentFile: "content/site.json",
+  mapFile: ".overlay-content/content-map.json",
+  draftFile: ".overlay-content/draft.json"
+};
+async function loadConfig(cwd) {
+  const configPath = import_node_path2.default.join(cwd, CONFIG_FILE);
+  const config = await readJsonFile(configPath);
+  if (config === null) {
+    throw new CliError(`Missing ${CONFIG_FILE}.`, {
+      hint: "Run: content-overlay init"
+    });
+  }
+  return validateOverlayConfig(config);
+}
+async function writeDefaultConfig(cwd, force = false) {
+  const configPath = import_node_path2.default.join(cwd, CONFIG_FILE);
+  const exists = await fileExists(configPath);
+  if (exists && !force) {
+    return { created: false, path: configPath };
+  }
+  await writeJsonFile(configPath, DEFAULT_CONFIG);
+  return { created: true, path: configPath };
+}
+
+// src/commands/edit.ts
+async function runEdit(options) {
+  if (!/^[a-z0-9._-]+$/i.test(options.key)) {
+    throw new CliError(`Invalid key "${options.key}".`, {
+      hint: "Keys should use letters, numbers, dots, hyphens, and underscores."
+    });
+  }
+  if (options.value.trim().length === 0) {
+    throw new CliError("Edit value cannot be empty.");
+  }
+  const config = await loadConfig(options.cwd);
+  const draftPath = import_node_path3.default.join(options.cwd, config.draftFile);
+  const contentPath = import_node_path3.default.join(options.cwd, config.contentFile);
+  const mapPath = import_node_path3.default.join(options.cwd, config.mapFile);
+  const rawContent = await readJsonFile(contentPath);
+  const content = rawContent === null ? {} : ensureStringRecord(rawContent, config.contentFile);
+  const rawDraft = await readJsonFile(draftPath);
+  const draft = rawDraft === null ? { ...content } : ensureStringRecord(rawDraft, config.draftFile);
+  const rawMap = await readJsonFile(mapPath);
+  const map = rawMap === null ? [] : ensureContentMap(rawMap);
+  const knownKeys = /* @__PURE__ */ new Set([...Object.keys(content), ...map.map((entry) => entry.key)]);
+  if (!knownKeys.has(options.key)) {
+    throw new CliError(`Unknown key "${options.key}".`, {
+      hint: "Run: content-overlay scan, then use one of the generated keys."
+    });
+  }
+  const oldValue = draft[options.key];
+  if (oldValue === options.value) {
+    console.log(`No change for key: ${options.key}`);
+    return;
+  }
+  draft[options.key] = options.value;
+  await writeJsonFile(draftPath, draft);
+  if (oldValue === void 0) {
+    console.log(`Created draft key: ${options.key}`);
+  } else {
+    console.log(`Updated draft key: ${options.key}`);
+    console.log(`Old: ${oldValue}`);
+  }
+  console.log(`New: ${options.value}`);
+}
+
+// src/commands/init.ts
+var import_node_path4 = __toESM(require("path"), 1);
+var import_node_fs2 = require("fs");
+async function runInit(options) {
+  const result = await writeDefaultConfig(options.cwd, options.force);
+  const activeConfig = result.created ? DEFAULT_CONFIG : await loadConfig(options.cwd);
+  if (result.created) {
+    console.log(`Created ${import_node_path4.default.relative(options.cwd, result.path)}`);
+  } else {
+    console.log("Config already exists. Use --force to overwrite.");
+  }
+  const contentFile = import_node_path4.default.join(options.cwd, activeConfig.contentFile);
+  const rawContent = await readJsonFile(contentFile);
+  const existingContent = rawContent === null ? null : ensureStringRecord(rawContent, activeConfig.contentFile);
+  if (!existingContent) {
+    await writeJsonFile(contentFile, {});
+    console.log(`Created ${activeConfig.contentFile}`);
+  }
+  const draftFile = import_node_path4.default.join(options.cwd, activeConfig.draftFile);
+  const rawDraft = await readJsonFile(draftFile);
+  const existingDraft = rawDraft === null ? null : ensureStringRecord(rawDraft, activeConfig.draftFile);
+  if (!existingDraft) {
+    await writeJsonFile(draftFile, existingContent ?? {});
+    console.log(`Created ${activeConfig.draftFile}`);
+  }
+  const mapFile = import_node_path4.default.join(options.cwd, activeConfig.mapFile);
+  const rawMap = await readJsonFile(mapFile);
+  if (rawMap === null) {
+    await writeJsonFile(mapFile, []);
+    console.log(`Created ${activeConfig.mapFile}`);
+  } else {
+    ensureContentMap(rawMap);
+  }
+  const packageJsonPath = import_node_path4.default.join(options.cwd, "package.json");
+  try {
+    const raw = await import_node_fs2.promises.readFile(packageJsonPath, "utf8");
+    const pkg = JSON.parse(raw);
+    const hasNext = Boolean(pkg.dependencies?.next || pkg.devDependencies?.next);
+    if (!hasNext) {
+      console.log("Warning: next dependency not found in package.json. This tool is built for Next.js App Router.");
+    }
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new CliError("Invalid package.json; unable to parse JSON.");
+    }
+    console.log("Warning: package.json not found. Run this in your Next.js project root.");
+  }
+  console.log("Init complete.");
+}
+
+// src/commands/publish.ts
+var import_node_path5 = __toESM(require("path"), 1);
+async function runPublish(options) {
+  const config = await loadConfig(options.cwd);
+  const contentPath = import_node_path5.default.join(options.cwd, config.contentFile);
+  const draftPath = import_node_path5.default.join(options.cwd, config.draftFile);
+  const publishMetaPath = import_node_path5.default.join(options.cwd, ".overlay-content/last-publish.json");
+  const rawContent = await readJsonFile(contentPath);
+  const content = rawContent === null ? {} : ensureStringRecord(rawContent, config.contentFile);
+  const rawDraft = await readJsonFile(draftPath);
+  const draft = rawDraft === null ? { ...content } : ensureStringRecord(rawDraft, config.draftFile);
+  const nextContent = { ...content, ...draft };
+  const candidateKeys = /* @__PURE__ */ new Set([...Object.keys(content), ...Object.keys(nextContent)]);
+  const changedKeys = [...candidateKeys].filter((key) => nextContent[key] !== content[key]);
+  if (changedKeys.length === 0) {
+    console.log("No draft changes to publish.");
+    return;
+  }
+  await writeJsonFile(contentPath, nextContent);
+  await writeJsonFile(draftPath, nextContent);
+  await writeJsonFile(publishMetaPath, {
+    publishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    changedKeys
+  });
+  console.log(`Published ${changedKeys.length} change(s) to ${config.contentFile}.`);
+  for (const key of changedKeys) {
+    console.log(`- ${key}`);
+  }
+}
+
+// src/commands/scan.ts
+var import_node_path7 = __toESM(require("path"), 1);
+var import_node_fs3 = require("fs");
+
+// src/lib/scan.ts
+var import_node_path6 = __toESM(require("path"), 1);
+var JSX_TEXT_REGEX = />([^<>{}\n]+)</g;
+function toSlug(input) {
+  return input.toLowerCase().replace(/[^a-z0-9\s-]/g, "").trim().replace(/\s+/g, "-").replace(/-+/g, "-").slice(0, 40);
+}
+function indexToLineCol(input, index) {
+  const before = input.slice(0, index);
+  const lines = before.split("\n");
+  const line = lines.length;
+  const column = lines[lines.length - 1].length + 1;
+  return { line, column };
+}
+function isUsefulText(text) {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  if (normalized.length < 3) return false;
+  if (!/[a-zA-Z]/.test(normalized)) return false;
+  if (normalized.startsWith("{") || normalized.endsWith("}")) return false;
+  return true;
+}
+function extractTextEntries(filePath, fileContents, cwd) {
+  const rel = import_node_path6.default.relative(cwd, filePath).replace(/\\/g, "/");
+  const relNoExt = rel.replace(/\.[^.]+$/, "");
+  const fileToken = relNoExt.replace(/\//g, ".");
+  const seen = /* @__PURE__ */ new Map();
+  const results = [];
+  for (const match of fileContents.matchAll(JSX_TEXT_REGEX)) {
+    const raw = match[1] ?? "";
+    const text = raw.replace(/\s+/g, " ").trim();
+    if (!isUsefulText(text)) continue;
+    const slug = toSlug(text);
+    if (!slug) continue;
+    const count = (seen.get(slug) ?? 0) + 1;
+    seen.set(slug, count);
+    const key = count === 1 ? `${fileToken}.${slug}` : `${fileToken}.${slug}-${count}`;
+    const position = indexToLineCol(fileContents, match.index ?? 0);
+    results.push({
+      key,
+      sourceFile: rel,
+      line: position.line,
+      column: position.column,
+      defaultValue: text
+    });
+  }
+  return results;
+}
+
+// src/commands/scan.ts
+async function runScan(options) {
+  const config = await loadConfig(options.cwd);
+  const extensions = new Set(config.extensions.map((ext) => ext.toLowerCase()));
+  const allFiles = [];
+  const existingDirs = [];
+  for (const dir of config.scanDirs) {
+    const dirPath = import_node_path7.default.join(options.cwd, dir);
+    try {
+      const stat = await import_node_fs3.promises.stat(dirPath);
+      if (!stat.isDirectory()) {
+        continue;
+      }
+      existingDirs.push(dir);
+    } catch {
+      continue;
+    }
+    const files = await collectFiles(dirPath, extensions);
+    allFiles.push(...files);
+  }
+  if (existingDirs.length === 0) {
+    throw new CliError("No scan directories found.", {
+      hint: `Expected one of: ${config.scanDirs.join(", ")}`
+    });
+  }
+  const uniqueFiles = [...new Set(allFiles)].sort((a, b) => a.localeCompare(b));
+  const map = [];
+  for (const filePath of uniqueFiles) {
+    const source = await import_node_fs3.promises.readFile(filePath, "utf8");
+    const entries = extractTextEntries(filePath, source, options.cwd);
+    map.push(...entries);
+  }
+  const contentPath = import_node_path7.default.join(options.cwd, config.contentFile);
+  const rawContent = await readJsonFile(contentPath);
+  const existingContent = rawContent === null ? {} : ensureStringRecord(rawContent, config.contentFile);
+  const nextContent = { ...existingContent };
+  let newKeys = 0;
+  for (const entry of map) {
+    if (!(entry.key in nextContent)) {
+      nextContent[entry.key] = entry.defaultValue;
+      newKeys += 1;
+    }
+  }
+  await writeJsonFile(import_node_path7.default.join(options.cwd, config.mapFile), map);
+  await writeJsonFile(contentPath, nextContent);
+  const draftPath = import_node_path7.default.join(options.cwd, config.draftFile);
+  const rawDraft = await readJsonFile(draftPath);
+  const existingDraft = rawDraft === null ? null : ensureStringRecord(rawDraft, config.draftFile);
+  const nextDraft = { ...nextContent, ...existingDraft ?? {} };
+  await writeJsonFile(draftPath, nextDraft);
+  console.log(`Scanned ${uniqueFiles.length} files.`);
+  console.log(`Found ${map.length} editable text nodes.`);
+  console.log(`Added ${newKeys} new keys to ${config.contentFile}.`);
+  if (map.length === 0) {
+    console.log("Warning: No text nodes found. Make sure files contain plain JSX text between tags.");
+  }
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+function printHelp() {
+  console.log("content-overlay <command> [options]");
+  console.log("");
+  console.log("Core flow: init -> scan -> edit -> publish");
+  console.log("");
+  console.log("Commands");
+  console.log("  init [--force]        Initialize config and content files");
+  console.log("  scan                  Scan source files and build content map");
+  console.log('  edit <key> "<value>"  Update one draft content value');
+  console.log("  publish               Publish draft values to content/site.json");
+  console.log("");
+  console.log("Flags");
+  console.log("  -h, --help            Show help");
+  console.log("  -v, --version         Show CLI version");
+}
+async function main() {
+  const [, , command, ...args] = process.argv;
+  const cwd = process.cwd();
+  try {
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+      printHelp();
+      return;
+    }
+    if (command === "--version" || command === "-v" || command === "version") {
+      console.log(VERSION);
+      return;
+    }
+    if (command === "init") {
+      const allowed = /* @__PURE__ */ new Set(["--force"]);
+      const unknown = args.filter((arg) => arg.startsWith("-") && !allowed.has(arg));
+      if (unknown.length > 0) {
+        throw new CliError(`Unknown option(s): ${unknown.join(", ")}`, {
+          hint: "Usage: content-overlay init [--force]"
+        });
+      }
+      const force = args.includes("--force");
+      await runInit({ cwd, force });
+      return;
+    }
+    if (command === "scan") {
+      if (args.length > 0) {
+        throw new CliError("scan does not accept arguments.", {
+          hint: "Usage: content-overlay scan"
+        });
+      }
+      await runScan({ cwd });
+      return;
+    }
+    if (command === "edit") {
+      if (args[0] === "--help" || args[0] === "-h") {
+        console.log('Usage: content-overlay edit <key> "<value>"');
+        return;
+      }
+      const key = args[0];
+      const value = args.slice(1).join(" ").trim();
+      if (!key || !value) {
+        throw new CliError("Missing required edit arguments.", {
+          hint: 'Usage: content-overlay edit <key> "<value>"'
+        });
+      }
+      await runEdit({ cwd, key, value });
+      return;
+    }
+    if (command === "publish") {
+      if (args.length > 0) {
+        throw new CliError("publish does not accept arguments.", {
+          hint: "Usage: content-overlay publish"
+        });
+      }
+      await runPublish({ cwd });
+      return;
+    }
+    throw new CliError(`Unknown command: ${command}`, {
+      hint: "Run: content-overlay --help"
+    });
+  } catch (error) {
+    const { message, hint } = toErrorMessage(error);
+    console.error(`Error: ${message}`);
+    if (hint) {
+      console.error(`Hint: ${hint}`);
+    }
+    process.exitCode = 1;
+  }
+}
+main();

package/dist/index.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,532 @@
+#!/usr/bin/env node
+
+// src/commands/edit.ts
+import path3 from "path";
+
+// src/lib/config.ts
+import path2 from "path";
+
+// src/lib/errors.ts
+var CliError = class extends Error {
+  code;
+  hint;
+  constructor(message, options) {
+    super(message);
+    this.name = "CliError";
+    this.code = options?.code ?? "CLI_ERROR";
+    this.hint = options?.hint;
+  }
+};
+function toErrorMessage(error) {
+  if (error instanceof CliError) {
+    return { message: error.message, hint: error.hint };
+  }
+  if (error instanceof Error) {
+    return { message: error.message };
+  }
+  return { message: String(error) };
+}
+
+// src/lib/fs.ts
+import { promises as fs } from "fs";
+import path from "path";
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readJsonFile(filePath) {
+  if (!await fileExists(filePath)) {
+    return null;
+  }
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, "utf8");
+  } catch {
+    throw new CliError(`Failed to read file: ${filePath}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new CliError(`Invalid JSON in file: ${filePath}`);
+  }
+}
+async function writeJsonFile(filePath, value) {
+  const dir = path.dirname(filePath);
+  try {
+    await ensureDir(dir);
+    await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+  } catch {
+    throw new CliError(`Failed to write file: ${filePath}`);
+  }
+}
+async function collectFiles(rootDir, extensions) {
+  const files = [];
+  async function walk(currentDir) {
+    let entries;
+    try {
+      entries = await fs.readdir(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".next" || entry.name === ".git") {
+          continue;
+        }
+        await walk(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      const ext = path.extname(entry.name).toLowerCase();
+      if (extensions.has(ext)) {
+        files.push(fullPath);
+      }
+    }
+  }
+  await walk(rootDir);
+  return files;
+}
+
+// src/lib/validation.ts
+function isPlainObject(input) {
+  return typeof input === "object" && input !== null && !Array.isArray(input);
+}
+function assertStringArray(input, fieldName) {
+  if (!Array.isArray(input) || input.some((value) => typeof value !== "string" || value.trim().length === 0)) {
+    throw new CliError(`Invalid ${fieldName} in content-overlay config.`, {
+      hint: `Expected "${fieldName}" to be a non-empty string array.`
+    });
+  }
+  return input;
+}
+function validateOverlayConfig(input) {
+  if (!isPlainObject(input)) {
+    throw new CliError("Invalid content-overlay config file.", {
+      hint: "Run: content-overlay init --force"
+    });
+  }
+  const version = input.version;
+  if (version !== 1) {
+    throw new CliError(`Unsupported config version: ${String(version)}.`, {
+      hint: "Run: content-overlay init --force"
+    });
+  }
+  const scanDirs = assertStringArray(input.scanDirs, "scanDirs");
+  const extensions = assertStringArray(input.extensions, "extensions");
+  const contentFile = input.contentFile;
+  const mapFile = input.mapFile;
+  const draftFile = input.draftFile;
+  if (typeof contentFile !== "string" || contentFile.trim().length === 0) {
+    throw new CliError("Invalid contentFile in content-overlay config.");
+  }
+  if (typeof mapFile !== "string" || mapFile.trim().length === 0) {
+    throw new CliError("Invalid mapFile in content-overlay config.");
+  }
+  if (typeof draftFile !== "string" || draftFile.trim().length === 0) {
+    throw new CliError("Invalid draftFile in content-overlay config.");
+  }
+  return {
+    version: 1,
+    scanDirs,
+    extensions,
+    contentFile,
+    mapFile,
+    draftFile
+  };
+}
+function ensureStringRecord(input, label) {
+  if (!isPlainObject(input)) {
+    throw new CliError(`Invalid ${label}; expected a JSON object.`, {
+      hint: "Run: content-overlay init"
+    });
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (typeof value !== "string") {
+      throw new CliError(`Invalid ${label}; key "${key}" must be a string.`);
+    }
+    result[key] = value;
+  }
+  return result;
+}
+function ensureContentMap(input) {
+  if (!Array.isArray(input)) {
+    throw new CliError("Invalid content map; expected an array.", {
+      hint: "Run: content-overlay scan"
+    });
+  }
+  const result = [];
+  for (const value of input) {
+    if (!isPlainObject(value)) {
+      throw new CliError("Invalid content map entry; expected object values.");
+    }
+    const { key, sourceFile, line, column, defaultValue } = value;
+    if (typeof key !== "string" || typeof sourceFile !== "string" || typeof line !== "number" || typeof column !== "number" || typeof defaultValue !== "string") {
+      throw new CliError("Invalid content map entry shape.", {
+        hint: "Run: content-overlay scan"
+      });
+    }
+    result.push({ key, sourceFile, line, column, defaultValue });
+  }
+  return result;
+}
+
+// src/lib/config.ts
+var CONFIG_FILE = "content-overlay.config.json";
+var DEFAULT_CONFIG = {
+  version: 1,
+  scanDirs: ["app", "components"],
+  extensions: [".tsx", ".ts", ".jsx", ".js", ".mdx"],
+  contentFile: "content/site.json",
+  mapFile: ".overlay-content/content-map.json",
+  draftFile: ".overlay-content/draft.json"
+};
+async function loadConfig(cwd) {
+  const configPath = path2.join(cwd, CONFIG_FILE);
+  const config = await readJsonFile(configPath);
+  if (config === null) {
+    throw new CliError(`Missing ${CONFIG_FILE}.`, {
+      hint: "Run: content-overlay init"
+    });
+  }
+  return validateOverlayConfig(config);
+}
+async function writeDefaultConfig(cwd, force = false) {
+  const configPath = path2.join(cwd, CONFIG_FILE);
+  const exists = await fileExists(configPath);
+  if (exists && !force) {
+    return { created: false, path: configPath };
+  }
+  await writeJsonFile(configPath, DEFAULT_CONFIG);
+  return { created: true, path: configPath };
+}
+
+// src/commands/edit.ts
+async function runEdit(options) {
+  if (!/^[a-z0-9._-]+$/i.test(options.key)) {
+    throw new CliError(`Invalid key "${options.key}".`, {
+      hint: "Keys should use letters, numbers, dots, hyphens, and underscores."
+    });
+  }
+  if (options.value.trim().length === 0) {
+    throw new CliError("Edit value cannot be empty.");
+  }
+  const config = await loadConfig(options.cwd);
+  const draftPath = path3.join(options.cwd, config.draftFile);
+  const contentPath = path3.join(options.cwd, config.contentFile);
+  const mapPath = path3.join(options.cwd, config.mapFile);
+  const rawContent = await readJsonFile(contentPath);
+  const content = rawContent === null ? {} : ensureStringRecord(rawContent, config.contentFile);
+  const rawDraft = await readJsonFile(draftPath);
+  const draft = rawDraft === null ? { ...content } : ensureStringRecord(rawDraft, config.draftFile);
+  const rawMap = await readJsonFile(mapPath);
+  const map = rawMap === null ? [] : ensureContentMap(rawMap);
+  const knownKeys = /* @__PURE__ */ new Set([...Object.keys(content), ...map.map((entry) => entry.key)]);
+  if (!knownKeys.has(options.key)) {
+    throw new CliError(`Unknown key "${options.key}".`, {
+      hint: "Run: content-overlay scan, then use one of the generated keys."
+    });
+  }
+  const oldValue = draft[options.key];
+  if (oldValue === options.value) {
+    console.log(`No change for key: ${options.key}`);
+    return;
+  }
+  draft[options.key] = options.value;
+  await writeJsonFile(draftPath, draft);
+  if (oldValue === void 0) {
+    console.log(`Created draft key: ${options.key}`);
+  } else {
+    console.log(`Updated draft key: ${options.key}`);
+    console.log(`Old: ${oldValue}`);
+  }
+  console.log(`New: ${options.value}`);
+}
+
+// src/commands/init.ts
+import path4 from "path";
+import { promises as fs2 } from "fs";
+async function runInit(options) {
+  const result = await writeDefaultConfig(options.cwd, options.force);
+  const activeConfig = result.created ? DEFAULT_CONFIG : await loadConfig(options.cwd);
+  if (result.created) {
+    console.log(`Created ${path4.relative(options.cwd, result.path)}`);
+  } else {
+    console.log("Config already exists. Use --force to overwrite.");
+  }
+  const contentFile = path4.join(options.cwd, activeConfig.contentFile);
+  const rawContent = await readJsonFile(contentFile);
+  const existingContent = rawContent === null ? null : ensureStringRecord(rawContent, activeConfig.contentFile);
+  if (!existingContent) {
+    await writeJsonFile(contentFile, {});
+    console.log(`Created ${activeConfig.contentFile}`);
+  }
+  const draftFile = path4.join(options.cwd, activeConfig.draftFile);
+  const rawDraft = await readJsonFile(draftFile);
+  const existingDraft = rawDraft === null ? null : ensureStringRecord(rawDraft, activeConfig.draftFile);
+  if (!existingDraft) {
+    await writeJsonFile(draftFile, existingContent ?? {});
+    console.log(`Created ${activeConfig.draftFile}`);
+  }
+  const mapFile = path4.join(options.cwd, activeConfig.mapFile);
+  const rawMap = await readJsonFile(mapFile);
+  if (rawMap === null) {
+    await writeJsonFile(mapFile, []);
+    console.log(`Created ${activeConfig.mapFile}`);
+  } else {
+    ensureContentMap(rawMap);
+  }
+  const packageJsonPath = path4.join(options.cwd, "package.json");
+  try {
+    const raw = await fs2.readFile(packageJsonPath, "utf8");
+    const pkg = JSON.parse(raw);
+    const hasNext = Boolean(pkg.dependencies?.next || pkg.devDependencies?.next);
+    if (!hasNext) {
+      console.log("Warning: next dependency not found in package.json. This tool is built for Next.js App Router.");
+    }
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new CliError("Invalid package.json; unable to parse JSON.");
+    }
+    console.log("Warning: package.json not found. Run this in your Next.js project root.");
+  }
+  console.log("Init complete.");
+}
+
+// src/commands/publish.ts
+import path5 from "path";
+async function runPublish(options) {
+  const config = await loadConfig(options.cwd);
+  const contentPath = path5.join(options.cwd, config.contentFile);
+  const draftPath = path5.join(options.cwd, config.draftFile);
+  const publishMetaPath = path5.join(options.cwd, ".overlay-content/last-publish.json");
+  const rawContent = await readJsonFile(contentPath);
+  const content = rawContent === null ? {} : ensureStringRecord(rawContent, config.contentFile);
+  const rawDraft = await readJsonFile(draftPath);
+  const draft = rawDraft === null ? { ...content } : ensureStringRecord(rawDraft, config.draftFile);
+  const nextContent = { ...content, ...draft };
+  const candidateKeys = /* @__PURE__ */ new Set([...Object.keys(content), ...Object.keys(nextContent)]);
+  const changedKeys = [...candidateKeys].filter((key) => nextContent[key] !== content[key]);
+  if (changedKeys.length === 0) {
+    console.log("No draft changes to publish.");
+    return;
+  }
+  await writeJsonFile(contentPath, nextContent);
+  await writeJsonFile(draftPath, nextContent);
+  await writeJsonFile(publishMetaPath, {
+    publishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    changedKeys
+  });
+  console.log(`Published ${changedKeys.length} change(s) to ${config.contentFile}.`);
+  for (const key of changedKeys) {
+    console.log(`- ${key}`);
+  }
+}
+
+// src/commands/scan.ts
+import path7 from "path";
+import { promises as fs3 } from "fs";
+
+// src/lib/scan.ts
+import path6 from "path";
+var JSX_TEXT_REGEX = />([^<>{}\n]+)</g;
+function toSlug(input) {
+  return input.toLowerCase().replace(/[^a-z0-9\s-]/g, "").trim().replace(/\s+/g, "-").replace(/-+/g, "-").slice(0, 40);
+}
+function indexToLineCol(input, index) {
+  const before = input.slice(0, index);
+  const lines = before.split("\n");
+  const line = lines.length;
+  const column = lines[lines.length - 1].length + 1;
+  return { line, column };
+}
+function isUsefulText(text) {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  if (normalized.length < 3) return false;
+  if (!/[a-zA-Z]/.test(normalized)) return false;
+  if (normalized.startsWith("{") || normalized.endsWith("}")) return false;
+  return true;
+}
+function extractTextEntries(filePath, fileContents, cwd) {
+  const rel = path6.relative(cwd, filePath).replace(/\\/g, "/");
+  const relNoExt = rel.replace(/\.[^.]+$/, "");
+  const fileToken = relNoExt.replace(/\//g, ".");
+  const seen = /* @__PURE__ */ new Map();
+  const results = [];
+  for (const match of fileContents.matchAll(JSX_TEXT_REGEX)) {
+    const raw = match[1] ?? "";
+    const text = raw.replace(/\s+/g, " ").trim();
+    if (!isUsefulText(text)) continue;
+    const slug = toSlug(text);
+    if (!slug) continue;
+    const count = (seen.get(slug) ?? 0) + 1;
+    seen.set(slug, count);
+    const key = count === 1 ? `${fileToken}.${slug}` : `${fileToken}.${slug}-${count}`;
+    const position = indexToLineCol(fileContents, match.index ?? 0);
+    results.push({
+      key,
+      sourceFile: rel,
+      line: position.line,
+      column: position.column,
+      defaultValue: text
+    });
+  }
+  return results;
+}
+
+// src/commands/scan.ts
+async function runScan(options) {
+  const config = await loadConfig(options.cwd);
+  const extensions = new Set(config.extensions.map((ext) => ext.toLowerCase()));
+  const allFiles = [];
+  const existingDirs = [];
+  for (const dir of config.scanDirs) {
+    const dirPath = path7.join(options.cwd, dir);
+    try {
+      const stat = await fs3.stat(dirPath);
+      if (!stat.isDirectory()) {
+        continue;
+      }
+      existingDirs.push(dir);
+    } catch {
+      continue;
+    }
+    const files = await collectFiles(dirPath, extensions);
+    allFiles.push(...files);
+  }
+  if (existingDirs.length === 0) {
+    throw new CliError("No scan directories found.", {
+      hint: `Expected one of: ${config.scanDirs.join(", ")}`
+    });
+  }
+  const uniqueFiles = [...new Set(allFiles)].sort((a, b) => a.localeCompare(b));
+  const map = [];
+  for (const filePath of uniqueFiles) {
+    const source = await fs3.readFile(filePath, "utf8");
+    const entries = extractTextEntries(filePath, source, options.cwd);
+    map.push(...entries);
+  }
+  const contentPath = path7.join(options.cwd, config.contentFile);
+  const rawContent = await readJsonFile(contentPath);
+  const existingContent = rawContent === null ? {} : ensureStringRecord(rawContent, config.contentFile);
+  const nextContent = { ...existingContent };
+  let newKeys = 0;
+  for (const entry of map) {
+    if (!(entry.key in nextContent)) {
+      nextContent[entry.key] = entry.defaultValue;
+      newKeys += 1;
+    }
+  }
+  await writeJsonFile(path7.join(options.cwd, config.mapFile), map);
+  await writeJsonFile(contentPath, nextContent);
+  const draftPath = path7.join(options.cwd, config.draftFile);
+  const rawDraft = await readJsonFile(draftPath);
+  const existingDraft = rawDraft === null ? null : ensureStringRecord(rawDraft, config.draftFile);
+  const nextDraft = { ...nextContent, ...existingDraft ?? {} };
+  await writeJsonFile(draftPath, nextDraft);
+  console.log(`Scanned ${uniqueFiles.length} files.`);
+  console.log(`Found ${map.length} editable text nodes.`);
+  console.log(`Added ${newKeys} new keys to ${config.contentFile}.`);
+  if (map.length === 0) {
+    console.log("Warning: No text nodes found. Make sure files contain plain JSX text between tags.");
+  }
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+function printHelp() {
+  console.log("content-overlay <command> [options]");
+  console.log("");
+  console.log("Core flow: init -> scan -> edit -> publish");
+  console.log("");
+  console.log("Commands");
+  console.log("  init [--force]        Initialize config and content files");
+  console.log("  scan                  Scan source files and build content map");
+  console.log('  edit <key> "<value>"  Update one draft content value');
+  console.log("  publish               Publish draft values to content/site.json");
+  console.log("");
+  console.log("Flags");
+  console.log("  -h, --help            Show help");
+  console.log("  -v, --version         Show CLI version");
+}
+async function main() {
+  const [, , command, ...args] = process.argv;
+  const cwd = process.cwd();
+  try {
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+      printHelp();
+      return;
+    }
+    if (command === "--version" || command === "-v" || command === "version") {
+      console.log(VERSION);
+      return;
+    }
+    if (command === "init") {
+      const allowed = /* @__PURE__ */ new Set(["--force"]);
+      const unknown = args.filter((arg) => arg.startsWith("-") && !allowed.has(arg));
+      if (unknown.length > 0) {
+        throw new CliError(`Unknown option(s): ${unknown.join(", ")}`, {
+          hint: "Usage: content-overlay init [--force]"
+        });
+      }
+      const force = args.includes("--force");
+      await runInit({ cwd, force });
+      return;
+    }
+    if (command === "scan") {
+      if (args.length > 0) {
+        throw new CliError("scan does not accept arguments.", {
+          hint: "Usage: content-overlay scan"
+        });
+      }
+      await runScan({ cwd });
+      return;
+    }
+    if (command === "edit") {
+      if (args[0] === "--help" || args[0] === "-h") {
+        console.log('Usage: content-overlay edit <key> "<value>"');
+        return;
+      }
+      const key = args[0];
+      const value = args.slice(1).join(" ").trim();
+      if (!key || !value) {
+        throw new CliError("Missing required edit arguments.", {
+          hint: 'Usage: content-overlay edit <key> "<value>"'
+        });
+      }
+      await runEdit({ cwd, key, value });
+      return;
+    }
+    if (command === "publish") {
+      if (args.length > 0) {
+        throw new CliError("publish does not accept arguments.", {
+          hint: "Usage: content-overlay publish"
+        });
+      }
+      await runPublish({ cwd });
+      return;
+    }
+    throw new CliError(`Unknown command: ${command}`, {
+      hint: "Run: content-overlay --help"
+    });
+  } catch (error) {
+    const { message, hint } = toErrorMessage(error);
+    console.error(`Error: ${message}`);
+    if (hint) {
+      console.error(`Hint: ${hint}`);
+    }
+    process.exitCode = 1;
+  }
+}
+main();

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "next-content-overlay",
+  "version": "0.1.0",
+  "description": "Simple overlay content workflow for Next.js App Router",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "content-overlay": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test tests/**/*.test.ts",
+    "license:check": "node scripts/license-check.mjs",
+    "check": "npm run typecheck && npm run test && npm run build && npm run license:check",
+    "prepack": "npm run check"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}