docs-for-me 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Manuel A. Cuerdo
+
+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,217 @@
+<p align="center">
+  <img src="https://i.pinimg.com/736x/7a/6d/a5/7a6da5d2962db34846138e08e2932f01.jpg" alt="docs-for-me logo" width="220">
+</p>
+
+<h1 align="center">docs-for-me</h1>
+
+<p align="center">
+  A CLI that creates programmer-friendly guides for files, folders, and Git changes.
+</p>
+
+It is meant for the everyday developer moment where you want to know:
+
+- What is in this file?
+- What does this folder contain?
+- What did I change before I commit?
+- What commit message can I copy after reviewing the changes?
+
+The output is Markdown, so it can be read in a terminal, saved beside a project,
+or deleted after review.
+
+## Install
+
+The intended install path is npm:
+
+```powershell
+npx docs-for-me --help
+```
+
+Or install it inside a project:
+
+```powershell
+npm install --save-dev docs-for-me
+npx docs-for-me changes --ai none --out changes-guide.md
+```
+
+This is the main distribution goal: users should not need to install Python,
+pip, or pipx just to use the tool.
+
+The first npm release ships with a bundled Windows x64 executable. macOS and
+Linux builds can be added after the Windows release flow is stable.
+
+## What It Does
+
+`docs-for-me` supports three main tasks:
+
+```bash
+docs-for-me file <path>
+docs-for-me folder <path>
+docs-for-me changes
+```
+
+It has two modes:
+
+- `--ai none` uses local static analysis and Git diff parsing.
+- `--ai opencode` asks OpenCode to write a fuller guide.
+
+Static mode is useful when you want quick local output. OpenCode mode is useful
+when you want a more natural explanation.
+
+## Basic Usage
+
+Document one file:
+
+```powershell
+docs-for-me file "app/(dashboard)/bookings/page.tsx" --ai none --out bookings-doc.md
+```
+
+Document one folder:
+
+```powershell
+docs-for-me folder app --ai none --out app-docs.md
+```
+
+Explain unstaged Git changes:
+
+```powershell
+docs-for-me changes --ai none --out changes-guide.md
+```
+
+Explain staged Git changes:
+
+```powershell
+docs-for-me changes --staged --ai none --out changes-guide.md
+```
+
+Compare changes since a branch or ref:
+
+```powershell
+docs-for-me changes --since main --ai none --out changes-guide.md
+```
+
+## OpenCode Mode
+
+OpenCode mode uses the `opencode` CLI as the AI provider.
+
+First, make sure OpenCode works:
+
+```powershell
+opencode run "Say hello in one sentence."
+```
+
+Then run:
+
+```powershell
+docs-for-me file "app/(dashboard)/bookings/page.tsx" --ai opencode --out bookings-ai-doc.md
+```
+
+Or for Git changes:
+
+```powershell
+docs-for-me changes --ai opencode --out changes-ai-guide.md
+```
+
+When OpenCode is working, the generated Markdown should not contain:
+
+```markdown
+- **AI:** unavailable or disabled (`opencode`)
+```
+
+## Contributor Setup
+
+The core CLI is written in Python, but npm is the user-facing package path.
+Use this setup only when developing `docs-for-me` itself:
+
+```powershell
+python -m venv .venv
+.venv\Scripts\activate
+pip install -e . pytest
+pytest
+```
+
+To build the Windows executable that the npm package runs:
+
+```powershell
+npm run build:exe:win
+```
+
+Then test the npm wrapper locally:
+
+```powershell
+npm run test:npm-local
+```
+
+The npm wrapper expects the executable here:
+
+```text
+prebuilt/win32-x64/docs-for-me.exe
+```
+
+When publishing to npm, that executable is included so users can run
+`npx docs-for-me ...` without setting up Python.
+
+If that line appears, `docs-for-me` fell back to static mode.
+
+## Git Changes Guide
+
+The `changes` command is designed for pre-commit review. It summarizes the diff,
+lists changed files, explains what the changes appear to do, and includes a
+copy-paste-ready commit message.
+
+Example output includes:
+
+```text
+update: search behavior and plan limits
+```
+
+Review the generated guide before committing. The guide is meant to save time,
+not replace your own final check.
+
+## Progress Messages
+
+Commands print progress messages so long-running AI calls do not look frozen:
+
+```text
+[  0.0s] Reading file: app/(dashboard)/bookings/page.tsx
+[  0.0s] Preparing documentation with provider: opencode
+[  0.0s] Waiting for AI response. This can take a moment...
+[  5.0s] OpenCode is reading the file and prompt...
+[ 10.0s] OpenCode is drafting the guide...
+```
+
+Hide progress messages with:
+
+```powershell
+docs-for-me file README.md --quiet
+```
+
+## Privacy
+
+`--ai none` runs locally and does not call an AI provider.
+
+`--ai opencode` sends the relevant file contents or Git diff to OpenCode and to
+whatever model/provider OpenCode is configured to use. Do not use AI mode on
+private or sensitive code unless you are comfortable with that provider handling
+the content.
+
+## Current Provider Support
+
+Today:
+
+- `none`
+- `opencode`
+
+The code is provider-based, so more providers can be added later.
+
+## Project Status
+
+`docs-for-me` is early-stage. It already works as a local CLI, but the package is
+not published yet.
+
+Good next steps:
+
+- improve README and packaging metadata
+- add a `LICENSE`
+- add config file support
+- add more AI providers
+- publish to PyPI

package/bin/docs-for-me.cjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+function platformKey() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  if (platform === "win32" && arch === "x64") {
+    return "win32-x64";
+  }
+
+  if (platform === "darwin" && arch === "arm64") {
+    return "darwin-arm64";
+  }
+
+  if (platform === "darwin" && arch === "x64") {
+    return "darwin-x64";
+  }
+
+  if (platform === "linux" && arch === "x64") {
+    return "linux-x64";
+  }
+
+  return `${platform}-${arch}`;
+}
+
+function executableName() {
+  return os.platform() === "win32" ? "docs-for-me.exe" : "docs-for-me";
+}
+
+const packageRoot = path.resolve(__dirname, "..");
+const binaryPath = path.join(packageRoot, "prebuilt", platformKey(), executableName());
+
+if (!fs.existsSync(binaryPath)) {
+  console.error("");
+  console.error("docs-for-me is installed, but no bundled executable was found for this platform.");
+  console.error("");
+  console.error(`Expected: ${binaryPath}`);
+  console.error("");
+  console.error("For users, install a released npm package that includes prebuilt binaries.");
+  console.error("For contributors, build one first:");
+  console.error("");
+  console.error("  npm run build:exe:win");
+  console.error("");
+  process.exit(1);
+}
+
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  cwd: process.cwd(),
+  env: process.env,
+  windowsHide: false,
+});
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 0);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "docs-for-me",
+  "version": "0.1.0",
+  "description": "Create programmer-friendly docs for files, folders, and Git changes.",
+  "license": "MIT",
+  "author": "John Manuel A. Cuerdo",
+  "homepage": "https://github.com/manwelAC/docs-for-me#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manwelAC/docs-for-me.git"
+  },
+  "bugs": {
+    "url": "https://github.com/manwelAC/docs-for-me/issues"
+  },
+  "bin": {
+    "docs-for-me": "./bin/docs-for-me.cjs"
+  },
+  "files": [
+    "bin/",
+    "prebuilt/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build:exe:win": "powershell -ExecutionPolicy Bypass -File scripts/build-windows-exe.ps1",
+    "pack:npm": "npm pack",
+    "test:npm-local": "node bin/docs-for-me.cjs --help"
+  },
+  "keywords": [
+    "documentation",
+    "developer-tools",
+    "cli",
+    "git",
+    "opencode",
+    "markdown"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "win32"
+  ],
+  "cpu": [
+    "x64"
+  ]
+}