@awilum/scope 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Sergey Romanenko
+
+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,381 @@
+# Scope
+
+Scope is a minimal, dependency-free command-line utility for exploring software projects and building a clean, structured project context as plain text.
+
+Scope runs locally, reads your project according to explicit rules, and produces deterministic text that can be copied into a chat, issue, review, documentation tool, or another text-based development environment.
+
+## Why Scope?
+
+When working on an unfamiliar codebase, developers often need a quick answer to: _What is in this project, and what does the relevant source actually contain?_ Scope turns that task into one command.
+
+```bash
+scope
+```
+
+The default command builds `scope-context.txt`, containing project metadata, statistics, a complete readable tree, and the contents of recognized text files.
+
+## Requirements
+
+- Node.js 18 or newer
+- npm
+- No runtime dependencies
+- No network connection
+
+## Installation
+
+Global installation from npm:
+
+```bash
+npm install -g @awilum/scope
+```
+
+Or from a local clone:
+
+```bash
+git clone <repository>
+cd scope
+npm install -g .
+```
+
+For local development, `npm link` is also supported:
+
+```bash
+npm link
+```
+
+Then verify:
+
+```bash
+scope --version
+```
+
+## Quick start
+
+From any project directory:
+
+```bash
+cd my-project
+scope init
+scope tree
+scope stats
+scope inspect src/index.js
+scope build
+```
+
+The shortest workflow is simply:
+
+```bash
+scope
+```
+
+which is equivalent to `scope build`.
+
+## Commands
+
+### `scope`
+
+Builds project context using the current directory and `.scope.json` if present.
+
+### `scope init`
+
+Creates `.scope.json` with sensible defaults. Existing configuration is never overwritten.
+
+### `scope build`
+
+Generates `scope-context.txt` by default.
+
+The output contains:
+
+1. project metadata;
+2. statistics;
+3. project tree;
+4. recognized text-file contents.
+
+File boundaries are explicit:
+
+```text
+FILE: src/app.js
+------------------
+import ...
+```
+
+Generated context contains no ANSI terminal escape sequences and uses relative paths for file content.
+
+### `scope tree`
+
+Displays a readable project tree.
+
+```bash
+scope tree
+scope tree 3
+scope tree --depth 2
+```
+
+### `scope stats`
+
+Displays file, directory, text/binary, size, line, skipped-file, and extension statistics.
+
+### `scope inspect <file>`
+
+Displays metadata and the content of one recognized text file.
+
+```bash
+scope inspect package.json
+scope inspect src/index.js
+```
+
+The path is resolved inside the current project root. Traversal outside the root is rejected.
+
+### `scope doctor`
+
+Checks Node.js, the project root, configuration, include paths, and output path.
+
+A missing `.scope.json` is normal: Scope simply uses defaults.
+
+### `scope help`
+
+Prints command help.
+
+### `scope --version`
+
+Prints the installed version.
+
+## JSON mode
+
+The tree, statistics, inspect, and doctor commands support machine-readable output:
+
+```bash
+scope tree --json
+scope stats --json
+scope inspect package.json --json
+scope doctor --json
+```
+
+JSON output contains no ANSI styling or progress messages and is suitable for scripts.
+
+## Configuration
+
+Scope looks for `.scope.json` in the current project root.
+
+Example:
+
+```json
+{
+  "output": "scope-context.txt",
+  "include": ["."],
+  "exclude": ["node_modules", ".git", "dist", "build", "coverage"],
+  "excludeFiles": ["package-lock.json", "yarn.lock", "pnpm-lock.yaml"],
+  "excludePaths": [],
+  "extensions": [".js", ".ts", ".tsx", ".json", ".md"],
+  "maxFileSize": 1048576
+}
+```
+
+### `output`
+
+Output filename for `scope build`. The output must remain inside the project root.
+
+### `include`
+
+Relative files or directories to process. The default is `["."]`.
+
+### `exclude`
+
+Directory names that are not traversed. Common generated and dependency directories are excluded by default.
+
+### `excludeFiles`
+
+Exact filenames that are skipped.
+
+### `excludePaths`
+
+Relative path prefixes that are skipped.
+
+### `extensions`
+
+Recognized textual file extensions. Files without extensions such as `Dockerfile`, `Makefile`, `Procfile`, `LICENSE`, and `README` are recognized as well.
+
+### `maxFileSize`
+
+Maximum file size read into context. The default is 1 MiB.
+
+## Security and privacy
+
+Scope is local-only. It does not upload, transmit, or call an external service.
+
+Sensitive files are skipped by default, including environment files and common private credentials such as `.pem`, `.key`, `.p12`, `.pfx`, `id_rsa`, `id_ed25519`, `credentials.json`, and `service-account.json`.
+
+Binary files are never copied into generated context. Files larger than `maxFileSize` are skipped from content generation.
+
+Configuration is an explicit trust boundary: if you intentionally add a sensitive file to an allowed configuration, you are responsible for that choice.
+
+## Generated context format
+
+A typical context looks like:
+
+```text
+PROJECT CONTEXT
+===============
+Project: my-project
+Root: /path/to/my-project
+Generated: 2026-09-27
+
+PROJECT STATISTICS
+==================
+Files: 42
+Directories: 9
+Text files: 37
+Binary files: 5
+Total size: 482.0 KB
+Context size: 310.2 KB
+Lines: 8421
+
+PROJECT TREE
+============
+src/
+  config.js
+  index.js
+package.json
+README.md
+
+FILES
+=====
+FILE: package.json
+------------------
+{ ... }
+
+FILE: src/index.js
+------------------
+import ...
+```
+
+The representation is deliberately plain text, stable, and easy to copy.
+
+## Supported text formats
+
+The default configuration recognizes common JavaScript, TypeScript, Python, Go, Rust, Java, Kotlin, Swift, C/C++, CSS, HTML, Vue, Svelte, Astro, JSON, YAML, XML, TOML, Markdown, shell, PHP, Ruby, SQL, GraphQL, SVG, and related formats.
+
+The extension list is configurable.
+
+## Development
+
+Run the CLI directly without installing it globally:
+
+```bash
+node bin/scope.js --version
+node bin/scope.js help
+```
+
+Check syntax:
+
+```bash
+npm run check
+```
+
+Test the CLI in the repository:
+
+```bash
+node bin/scope.js doctor
+node bin/scope.js tree
+node bin/scope.js stats
+node bin/scope.js inspect package.json
+node bin/scope.js build
+```
+
+Then test the global command:
+
+```bash
+npm install -g .
+scope --version
+```
+
+Or:
+
+```bash
+npm link
+scope --version
+```
+
+## Publishing to npm
+
+After choosing and confirming an available package name and authenticating with npm:
+
+```bash
+npm publish --access public
+```
+
+For the scoped package name used by this repository:
+
+```bash
+npm install -g @awilum/scope
+```
+
+## GitHub usage
+
+The repository is intentionally small and can be inspected without learning a framework. A typical first commit is:
+
+```bash
+git init
+git add .
+git commit -m "Initial release"
+git remote add origin <repository>
+git push -u origin main
+```
+
+The repository intentionally excludes `node_modules`, generated context files, logs, and macOS metadata.
+
+## Troubleshooting
+
+### `scope: command not found`
+
+Confirm that the global npm bin directory is on your `PATH`, then reinstall:
+
+```bash
+npm install -g .
+```
+
+### Configuration errors
+
+Run:
+
+```bash
+scope doctor
+```
+
+Fix the reported `.scope.json` values and run the command again.
+
+### A file is missing from context
+
+Check whether it is:
+
+- excluded by directory name;
+- listed in `excludeFiles` or `excludePaths`;
+- a recognized text extension;
+- larger than `maxFileSize`;
+- recognized as a sensitive file.
+
+Use `scope stats` to see skipped counts.
+
+### A file is outside the configured root
+
+Scope intentionally refuses `inspect` paths that resolve outside the current project root.
+
+## Project structure
+
+```text
+scope/
+├── bin/
+│   └── scope.js
+├── examples/
+├── .gitignore
+├── .scope.json.example
+├── LICENSE
+├── package.json
+└── README.md
+```
+
+The implementation intentionally stays concentrated in one CLI file. Scope is a utility, not a framework.
+
+## License
+
+MIT. See `LICENSE`.

package/bin/scope.js

@@ -0,0 +1,612 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import process from "node:process";
+
+const VERSION = "1.0.0";
+const DEFAULT_CONFIG = {
+  output: "scope-context.txt",
+  include: ["."],
+  exclude: [
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "coverage",
+    ".cache",
+    ".next",
+    ".vite",
+    ".venv",
+    "__pycache__",
+    ".idea",
+    ".vscode",
+    ".DS_Store",
+  ],
+  excludeFiles: ["package-lock.json", "yarn.lock", "pnpm-lock.yaml"],
+  excludePaths: [],
+  extensions: [
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".ts",
+    ".tsx",
+    ".py",
+    ".go",
+    ".rs",
+    ".java",
+    ".kt",
+    ".swift",
+    ".c",
+    ".cpp",
+    ".h",
+    ".hpp",
+    ".css",
+    ".scss",
+    ".sass",
+    ".less",
+    ".html",
+    ".htm",
+    ".vue",
+    ".svelte",
+    ".astro",
+    ".json",
+    ".jsonc",
+    ".yaml",
+    ".yml",
+    ".xml",
+    ".toml",
+    ".ini",
+    ".env.example",
+    ".md",
+    ".mdx",
+    ".txt",
+    ".sh",
+    ".bash",
+    ".zsh",
+    ".php",
+    ".rb",
+    ".sql",
+    ".graphql",
+    ".gql",
+    ".svg",
+  ],
+  maxFileSize: 1048576,
+};
+const SPECIAL = new Set([
+  "Dockerfile",
+  "Makefile",
+  "Procfile",
+  "LICENSE",
+  "README",
+  "README.md",
+  "README.txt",
+  ".scope.json",
+  ".gitignore",
+]);
+const SECRET_NAMES = new Set([
+  ".env",
+  ".env.local",
+  ".env.production",
+  ".env.development",
+  "credentials.json",
+  "service-account.json",
+  "id_rsa",
+  "id_ed25519",
+]);
+const SECRET_EXTENSIONS = new Set([".pem", ".key", ".p12", ".pfx"]);
+
+const ansi = (code, s) =>
+  process.stdout.isTTY ? `\x1b[${code}m${s}\x1b[0m` : s;
+const bold = (s) => ansi(1, s);
+const dim = (s) => ansi(2, s);
+const green = (s) => ansi(32, s);
+const red = (s) => ansi(31, s);
+const yellow = (s) => ansi(33, s);
+const cyan = (s) => ansi(36, s);
+const fail = (message, code = 1) => {
+  console.error(`${red("✗")} ${message}`);
+  process.exitCode = code;
+};
+const humanSize = (bytes) => {
+  const units = ["B", "KB", "MB", "GB"];
+  let n = bytes,
+    i = 0;
+  while (n >= 1024 && i < units.length - 1) {
+    n /= 1024;
+    i++;
+  }
+  return `${n.toFixed(i ? 1 : 0)} ${units[i]}`;
+};
+const rel = (root, p) => path.relative(root, p) || ".";
+
+function parseArgs(argv) {
+  const args = { _: [], json: false, depth: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") args.json = true;
+    else if (a === "--help" || a === "-h") args.help = true;
+    else if (a === "--version" || a === "-v") args.version = true;
+    else if (a === "--depth") {
+      const v = argv[++i];
+      args.depth = Number(v);
+    } else if (a.startsWith("--depth=")) args.depth = Number(a.slice(8));
+    else args._.push(a);
+  }
+  return args;
+}
+
+function loadConfig(root) {
+  const file = path.join(root, ".scope.json");
+  if (!fs.existsSync(file))
+    return { config: { ...DEFAULT_CONFIG }, exists: false, error: null };
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    const c = { ...DEFAULT_CONFIG, ...raw };
+    if (
+      !Array.isArray(c.include) ||
+      !Array.isArray(c.exclude) ||
+      !Array.isArray(c.excludeFiles) ||
+      !Array.isArray(c.excludePaths) ||
+      !Array.isArray(c.extensions)
+    )
+      throw new Error(
+        "include, exclude, excludeFiles, excludePaths and extensions must be arrays",
+      );
+    if (typeof c.output !== "string" || !c.output.trim())
+      throw new Error("output must be a non-empty string");
+    if (!Number.isInteger(c.maxFileSize) || c.maxFileSize <= 0)
+      throw new Error("maxFileSize must be a positive integer");
+    return { config: c, exists: true, error: null };
+  } catch (e) {
+    return { config: { ...DEFAULT_CONFIG }, exists: true, error: e.message };
+  }
+}
+
+function isSecret(relPath) {
+  const normalized = relPath.split(path.sep).join("/");
+  const base = path.basename(normalized);
+  if (SECRET_NAMES.has(base)) return true;
+  if ([...SECRET_EXTENSIONS].some((ext) => base.endsWith(ext))) return true;
+  if (base.startsWith(".env.") && base !== ".env.example") return true;
+  return false;
+}
+function isAllowedFile(name, config) {
+  if (SPECIAL.has(name)) return true;
+  const lower = name.toLowerCase();
+  return config.extensions.some((ext) => lower.endsWith(ext.toLowerCase()));
+}
+function shouldExclude(relPath, config) {
+  const parts = relPath.split(path.sep).filter(Boolean);
+  if (parts.some((p) => config.exclude.includes(p))) return true;
+  if (config.excludeFiles.includes(path.basename(relPath))) return true;
+  const normalized = relPath.split(path.sep).join("/");
+  return config.excludePaths.some(
+    (p) =>
+      normalized === p || normalized.startsWith(p.replace(/\/$/, "") + "/"),
+  );
+}
+function inside(root, target) {
+  const r = path.resolve(root),
+    t = path.resolve(target);
+  return t === r || t.startsWith(r + path.sep);
+}
+function includedByConfig(relPath, config) {
+  const clean = relPath.split(path.sep).join("/");
+  return config.include.some(
+    (item) =>
+      item === "." ||
+      clean === item ||
+      clean.startsWith(item.replace(/\/$/, "") + "/"),
+  );
+}
+function walk(root, config) {
+  const entries = [];
+  const skipped = [];
+  const seen = new Set();
+  const visit = (dir) => {
+    let names;
+    try {
+      names = fs
+        .readdirSync(dir, { withFileTypes: true })
+        .sort((a, b) => a.name.localeCompare(b.name));
+    } catch (e) {
+      skipped.push({ path: rel(root, dir), reason: e.code || e.message });
+      return;
+    }
+    for (const ent of names) {
+      const full = path.join(dir, ent.name),
+        rp = rel(root, full);
+      if (shouldExclude(rp, config) || !includedByConfig(rp, config)) continue;
+      let st;
+      try {
+        st = fs.lstatSync(full);
+      } catch (e) {
+        skipped.push({ path: rp, reason: e.code || e.message });
+        continue;
+      }
+      if (st.isSymbolicLink()) {
+        let target;
+        try {
+          target = fs.realpathSync(full);
+          if (!inside(root, target))
+            skipped.push({ path: rp, reason: "symlink outside project root" });
+          else {
+            const key = fs.realpathSync(full);
+            if (!seen.has(key)) {
+              seen.add(key);
+              const ts = fs.statSync(full);
+              if (ts.isDirectory()) visit(full);
+              else
+                entries.push({
+                  path: rp,
+                  type: "file",
+                  size: ts.size,
+                  symlink: true,
+                });
+            }
+          }
+        } catch (e) {
+          skipped.push({ path: rp, reason: "broken symbolic link" });
+        }
+        continue;
+      }
+      if (st.isDirectory()) {
+        entries.push({ path: rp, type: "directory" });
+        visit(full);
+        continue;
+      }
+      if (st.isFile()) {
+        if (isSecret(rp)) {
+          skipped.push({ path: rp, reason: "sensitive file" });
+          continue;
+        }
+        const textual = isAllowedFile(ent.name, config);
+        entries.push({
+          path: rp,
+          type: "file",
+          size: st.size,
+          textual,
+          tooLarge: st.size > config.maxFileSize,
+        });
+      }
+    }
+  };
+  visit(root);
+  return { entries, skipped };
+}
+function inspectFile(root, config, file) {
+  const target = path.resolve(root, file);
+  if (!inside(root, target))
+    throw new Error("Path is outside the project root");
+  if (!fs.existsSync(target)) throw new Error(`File does not exist: ${file}`);
+  const st = fs.lstatSync(target);
+  if (!st.isFile()) throw new Error("Path is not a regular file");
+  const rp = rel(root, target);
+  if (isSecret(rp)) throw new Error("Refusing to inspect a sensitive file");
+  if (!isAllowedFile(path.basename(target), config))
+    throw new Error("File type is not recognized as text");
+  if (st.size > config.maxFileSize)
+    throw new Error(
+      `File exceeds maxFileSize (${humanSize(config.maxFileSize)})`,
+    );
+  const content = fs.readFileSync(target, "utf8");
+  return {
+    path: rp,
+    size: st.size,
+    lines: content === "" ? 0 : content.split(/\r?\n/).length,
+    encoding: "UTF-8",
+    content,
+  };
+}
+function projectData(root, config) {
+  const { entries, skipped } = walk(root, config);
+  const files = entries.filter((e) => e.type === "file");
+  const dirs = entries.filter((e) => e.type === "directory");
+  const text = files.filter((e) => e.textual && !e.tooLarge);
+  const binary = files.filter((e) => !e.textual);
+  const tooLarge = files.filter((e) => e.tooLarge);
+  const ext = {};
+  let contextSize = 0,
+    totalLines = 0;
+  for (const f of text) {
+    const extn = path.extname(f.path).toLowerCase() || "[no extension]";
+    ext[extn] = (ext[extn] || 0) + 1;
+    try {
+      const c = fs.readFileSync(path.join(root, f.path), "utf8");
+      contextSize += Buffer.byteLength(c);
+      totalLines += c === "" ? 0 : c.split(/\r?\n/).length;
+    } catch {}
+  }
+  return {
+    entries,
+    skipped,
+    files,
+    dirs,
+    text,
+    binary,
+    tooLarge,
+    stats: {
+      files: files.length,
+      directories: dirs.length,
+      textFiles: text.length,
+      binaryFiles: binary.length,
+      totalSize: files.reduce((n, f) => n + f.size, 0),
+      contextSize,
+      lines: totalLines,
+      extensions: ext,
+      excluded: skipped.length,
+    },
+  };
+}
+function treeText(data, depth = Infinity) {
+  const nodes = new Map([[".", []]]);
+  for (const e of data.entries) {
+    const parts = e.path.split(path.sep);
+    if (parts.length > depth + 1) continue;
+    let cur = ".";
+    for (let i = 0; i < parts.length; i++) {
+      const p = parts[i],
+        key = cur + "/" + p;
+      if (!nodes.has(cur)) nodes.set(cur, []);
+      if (!nodes.get(cur).some((x) => x.name === p))
+        nodes
+          .get(cur)
+          .push({
+            name: p,
+            type: i === parts.length - 1 ? e.type : "directory",
+          });
+      cur = key;
+      if (!nodes.has(cur)) nodes.set(cur, []);
+    }
+  }
+  const lines = [];
+  const render = (parent, prefix) => {
+    const kids = (nodes.get(parent) || []).sort((a, b) =>
+      a.type === b.type
+        ? a.name.localeCompare(b.name)
+        : a.type === "directory"
+          ? -1
+          : 1,
+    );
+    for (const k of kids) {
+      lines.push(prefix + k.name + (k.type === "directory" ? "/" : ""));
+      if (k.type === "directory") render(parent + "/" + k.name, prefix + "  ");
+    }
+  };
+  render(".", "");
+  return lines.join("\n");
+}
+function contextText(root, data, config) {
+  const name = path.basename(root);
+  const s = data.stats;
+  const lines = [];
+  lines.push(
+    "PROJECT CONTEXT",
+    "===============",
+    `Project: ${name}`,
+    `Root: ${root}`,
+    `Generated: ${new Date().toISOString().slice(0, 10)}`,
+    "",
+    "PROJECT STATISTICS",
+    "==================",
+    `Files: ${s.files}`,
+    `Directories: ${s.directories}`,
+    `Text files: ${s.textFiles}`,
+    `Binary files: ${s.binaryFiles}`,
+    `Total size: ${humanSize(s.totalSize)}`,
+    `Context size: ${humanSize(s.contextSize)}`,
+    `Lines: ${s.lines}`,
+    "",
+    "PROJECT TREE",
+    "============",
+    treeText(data),
+    "",
+    "FILES",
+    "=====",
+  );
+  for (const f of data.text.sort((a, b) => a.path.localeCompare(b.path))) {
+    let content;
+    try {
+      content = fs.readFileSync(path.join(root, f.path), "utf8");
+    } catch {
+      continue;
+    }
+    lines.push(
+      `FILE: ${f.path}`,
+      "------------------",
+      content.replace(/\r\n/g, "\n").replace(/\u0000/g, ""),
+    );
+  }
+  return lines.join("\n") + "\n";
+}
+function printHelp() {
+  console.log(
+    `${bold("Scope")} — minimal project exploration and context builder\n\nUsage:\n  scope [command] [options]\n\nCommands:\n  scope             Build project context (same as scope build)\n  scope init        Create .scope.json\n  scope build       Generate scope-context.txt\n  scope tree        Show project tree\n  scope stats       Show project statistics\n  scope inspect <file>  Show file metadata and content\n  scope doctor      Check project/configuration health\n  scope help        Show this help\n\nOptions:\n  -h, --help        Show help\n  -v, --version     Show version\n  --json            Machine-readable JSON output\n  --depth <n>       Limit tree depth\n\nExamples:\n  scope\n  scope init\n  scope tree 3\n  scope tree --depth 2\n  scope stats --json\n  scope inspect src/index.js\n  scope build`,
+  );
+}
+function init(root) {
+  const file = path.join(root, ".scope.json");
+  if (fs.existsSync(file)) {
+    console.log(
+      `${yellow("!")} .scope.json already exists. Nothing was overwritten.`,
+    );
+    return;
+  }
+  fs.writeFileSync(file, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n");
+  console.log(`${green("✓")} Created .scope.json`);
+}
+function doctor(root, configInfo) {
+  const checks = [];
+  checks.push({
+    name: "Node.js",
+    ok: Number(process.versions.node.split(".")[0]) >= 18,
+    value: process.version,
+  });
+  checks.push({ name: "Project root", ok: fs.existsSync(root), value: root });
+  checks.push({
+    name: "Configuration",
+    ok: !configInfo.error,
+    value: configInfo.exists ? ".scope.json" : "defaults",
+  });
+  if (!configInfo.error) {
+    for (const p of configInfo.config.include) {
+      const t = path.resolve(root, p);
+      checks.push({
+        name: `Include: ${p}`,
+        ok: inside(root, t) && fs.existsSync(t),
+        value: inside(root, t) ? t : "outside root",
+      });
+    }
+    const out = path.resolve(root, configInfo.config.output);
+    checks.push({ name: "Output path", ok: inside(root, out), value: out });
+  }
+  return checks;
+}
+
+function main() {
+  const root = process.cwd(),
+    args = parseArgs(process.argv.slice(2));
+  if (args.version) {
+    console.log(VERSION);
+    return;
+  }
+  if (args.help || args._[0] === "help") {
+    printHelp();
+    return;
+  }
+  const command = args._[0] || "build";
+  const configInfo = loadConfig(root);
+  if (configInfo.error && command !== "doctor") {
+    fail(`Invalid .scope.json: ${configInfo.error}`);
+    return;
+  }
+  const config = configInfo.config;
+  try {
+    if (command === "init") {
+      init(root);
+      return;
+    }
+    if (command === "doctor") {
+      const checks = doctor(root, configInfo);
+      if (args.json) {
+        console.log(
+          JSON.stringify({ ok: checks.every((c) => c.ok), checks }, null, 2),
+        );
+        return;
+      }
+      console.log(
+        bold("SCOPE DOCTOR"),
+        "\n────────────\n" +
+          checks
+            .map(
+              (c) =>
+                `  ${c.ok ? green("✓") : red("✗")} ${c.name.padEnd(18)} ${c.value}`,
+            )
+            .join("\n") +
+          "\n" +
+          (checks.every((c) => c.ok)
+            ? "No problems found."
+            : "Problems found."),
+      );
+      if (!checks.every((c) => c.ok)) process.exitCode = 1;
+      return;
+    }
+    if (!["build", "tree", "stats", "inspect"].includes(command)) {
+      fail(`Unknown command: ${command}\nRun: scope help`);
+      return;
+    }
+    const data = projectData(root, config);
+    if (command === "tree") {
+      let depth = args.depth;
+      if (depth === null && args._[1]) depth = Number(args._[1]);
+      if (depth !== null && (!Number.isInteger(depth) || depth < 0)) {
+        fail("Depth must be a non-negative integer");
+        return;
+      }
+      const out = {
+        root,
+        tree: treeText(data, depth === null ? Infinity : depth),
+        entries: data.entries,
+      };
+      if (args.json) {
+        console.log(JSON.stringify(out, null, 2));
+        return;
+      }
+      console.log(
+        bold("PROJECT TREE"),
+        "\n─────────────\n" + treeText(data, depth === null ? Infinity : depth),
+      );
+      return;
+    }
+    if (command === "stats") {
+      const out = { root, stats: data.stats };
+      if (args.json) {
+        console.log(JSON.stringify(out, null, 2));
+        return;
+      }
+      const ex = Object.entries(data.stats.extensions).sort(
+        (a, b) => b[1] - a[1],
+      );
+      console.log(
+        bold("PROJECT STATISTICS"),
+        "\n──────────────────\n" +
+          `  Files             ${data.stats.files}\n  Directories       ${data.stats.directories}\n  Text files        ${data.stats.textFiles}\n  Binary files      ${data.stats.binaryFiles}\n  Total size        ${humanSize(data.stats.totalSize)}\n  Context size      ${humanSize(data.stats.contextSize)}\n  Lines             ${data.stats.lines}\n  Skipped           ${data.stats.excluded}\n  Extensions\n` +
+          ex.map(([k, v]) => `    ${k.padEnd(14)} ${v}`).join("\n"),
+      );
+      return;
+    }
+    if (command === "inspect") {
+      if (!args._[1]) {
+        fail("Missing file path. Example: scope inspect src/index.js");
+        return;
+      }
+      const info = inspectFile(root, config, args._[1]);
+      if (args.json) {
+        console.log(JSON.stringify(info, null, 2));
+        return;
+      }
+      console.log(
+        bold("FILE"),
+        "\n────\n" +
+          `  Path        ${info.path}\n  Size        ${humanSize(info.size)}\n  Lines       ${info.lines}\n  Encoding    ${info.encoding}\n\n` +
+          bold("CONTENT"),
+        "\n───────\n" + info.content,
+      );
+      return;
+    }
+    const output = path.resolve(root, config.output);
+    if (!inside(root, output))
+      throw new Error(
+        "Configured output path must stay inside the project root",
+      );
+    const context = contextText(root, data, config);
+    fs.writeFileSync(output, context, "utf8");
+    if (args.json) {
+      console.log(
+        JSON.stringify(
+          {
+            ok: true,
+            root,
+            output,
+            files: data.text.length,
+            contextSize: Buffer.byteLength(context),
+            durationMs: 0,
+          },
+          null,
+          2,
+        ),
+      );
+      return;
+    }
+    console.log(
+      bold("PROJECT CONTEXT BUILDER"),
+      "\n────────────────────────\n" +
+        `Project\n───────\n  Root     ${root}\n  Output   ${rel(root, output)}\n\nScanning\n────────\n  ${green("✓")} Found ${data.text.length} text files\n\nBuilding Context\n────────────────\n  ${green("✓")} ${data.text.length} files included\n\nComplete\n────────\n  ${green("✓")} Context generated successfully\n  Files         ${data.text.length}\n  Context size  ${humanSize(Buffer.byteLength(context))}\n  Output        ${output}\nContext build finished successfully.`,
+    );
+  } catch (e) {
+    fail(e.message || String(e));
+  }
+}
+main();

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@awilum/scope",
+  "version": "1.0.0",
+  "description": "A minimal dependency-free CLI for exploring projects and building structured project context.",
+  "license": "MIT",
+  "author": {
+    "name": "Sergey Romanenko",
+    "email": "awilum@msn.com",
+    "url": "https://github.com/Awilum"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Awilum/scope.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Awilum/scope/issues"
+  },
+  "homepage": "https://github.com/Awilum/scope",
+  "type": "module",
+  "bin": {
+    "scope": "./bin/scope.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE",
+    ".scope.json.example"
+  ],
+  "keywords": [
+    "cli",
+    "developer-tools",
+    "project-context",
+    "codebase",
+    "source-code",
+    "project-explorer",
+    "code-explorer",
+    "context",
+    "unix",
+    "nodejs"
+  ],
+  "scripts": {
+    "check": "node --check bin/scope.js",
+    "test": "node --test",
+    "test:cli": "node bin/scope.js doctor --json",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "pack:check": "npm pack --dry-run"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.0",
+    "prettier": "^3.9.9"
+  }
+}