md2wiki 1.0.0 → 1.0.1

package/README.md

@@ -3,8 +3,8 @@
   <img src="public/logo.svg" alt="md2wiki logo" width="160" />
   <br />
   <h1>🔄 MD2WIKI</h1>
-  <p><strong>Real-Time Markdown to MediaWiki Wikitext Compiler</strong></p>
-  <p><i>A premium, high-density Next.js utility for Wikipedia editors featuring SUL OAuth 2.0 Sandbox publishing and CORS-free repository README importing.</i></p>
+  <p><strong>Real-Time Markdown to MediaWiki Wikitext Converter</strong></p>
+  <p><i>A premium Next.js utility for Wikipedia editors featuring SUL OAuth 2.0 Sandbox publishing and CORS-free repository README importing.</i></p>
 
   <br />
 
@@ -25,23 +25,20 @@
 
 ## 🧭 Navigation
 
-* [📐 The Project Vision](#-the-project-vision)
+* [📐 Project Vision](#-project-vision)
 * [✨ Key Features](#-key-features)
-* [🚀 Quick Start (Local Setup)](#-quick-start-local-setup)
-* [🔒 OAuth 2.0 Credentials Setup](#-oauth-20-credentials-setup)
-* [📦 Deployment to Toolforge](#-deployment-to-toolforge)
-* [📂 Project Structure](#-project-structure)
-* [🧪 Running Unit Tests](#-running-unit-tests)
+* [🚀 Local Quick Start](#-local-quick-start)
+* [🔒 SUL OAuth 2.0 Credentials](#-sul-oauth-20-credentials)
+* [📦 Toolforge Deployment](#-toolforge-deployment)
+* [💻 Command Line Interface (CLI)](#-command-line-interface-cli)
 
 ---
 
-## 📐 The Project Vision
+## 📐 Project Vision
 
-Writing high-quality drafts or documentation offline in Markdown is standard practice for modern developers. However, publishing these drafts on Wikipedia talk pages, user sandboxes, or Meta-Wiki documentation requires manually converting markdown format to MediaWiki Wikitext markup. 
+Publishing Markdown drafts (offline notes, documentation, readmes) onto Wikipedia talk pages, user sandboxes, or Meta-Wiki requires translating the content into MediaWiki Wikitext markup. 
 
-**md2wiki** solves this pain point. It serves as:
-1. **An NPM-ready parser module** (`src/core/parser.ts`) that compiles Markdown to wikitext with smart rules.
-2. **A SUL-integrated Toolforge service** that allows editors to paste raw Markdown (or fetch direct GitHub/GitLab READMEs) and publish the compiled Wikitext straight to their Wikipedia Sandbox with a single click.
+**md2wiki** is a high-density, real-time translator that processes markdown formatting on the fly and integrates securely with your Wikipedia single user login (SUL) to write the output directly to your user sandbox page with one click.
 
 ---
 
@@ -74,7 +71,7 @@ Writing high-quality drafts or documentation offline in Markdown is standard pra
 
 ---
 
-## 🚀 Quick Start (Local Setup)
+## 🚀 Local Quick Start
 
 Follow these steps to run the application on your local machine:
 
@@ -90,7 +87,7 @@ npm install
 ```
 
 ### 3. Set up environment variables
-Create a `.env` file in the root directory (the application will run in **Mock SUL Mode** automatically if credentials are left blank):
+Create a `.env` file in the root directory (the application runs in **Mock SUL Mode** automatically if credentials are left blank):
 ```env
 WIKIMEDIA_CLIENT_ID=your_oauth_consumer_token
 WIKIMEDIA_CLIENT_SECRET=your_oauth_secret_token
@@ -106,75 +103,60 @@ Open **[http://localhost:8000](http://localhost:8000)** in your browser.
 
 ---
 
-## 🔒 OAuth 2.0 Credentials Setup
+## 🔒 SUL OAuth 2.0 Credentials
 
-To write to Wikipedia Sandboxes on behalf of users, you must register the tool:
+To enable sandbox publishing, register the tool:
 
 1. Log in to [Meta-Wiki](https://meta.wikimedia.org/).
 2. Navigate to [Special:OAuthConsumerRegistration/propose/oauth2](https://meta.wikimedia.org/wiki/Special:OAuthConsumerRegistration/propose/oauth2).
 3. Set the parameters:
    * **OAuth callback URL**: `https://md2wiki.toolforge.org/api/auth/callback` (or `http://localhost:8000/api/auth/callback` for dev).
    * **Grants**: Select **Basic rights** (`basic`), **Edit existing pages** (`edit`), and **Create, edit, and move pages** (`writepage` / `create`).
-   * **Allowed pages**: Leave blank to allow editing of all pages (required since sandbox pages reside under user namespaces).
 4. Submit and record your **Consumer Token** and **Secret Token**.
 
 ---
 
-## 📦 Deployment to Toolforge
+## 📦 Toolforge Deployment
 
 Wikimedia Toolforge supports hosting Node.js Next.js web applications using Kubernetes.
 
-### 1. Log in to Toolforge Bastion
+### 1. SSH into Toolforge Bastion
 ```bash
 ssh <username>@login.toolforge.org
+become <tool-name>
 ```
 
-### 2. Initialize the Node webservice
-Ensure your project files are cloned in your Toolforge home directory `$HOME/www/js/`:
+### 2. Clone and install dependencies
+Ensure files are cloned in your Toolforge home directory `www/js/`:
 ```bash
+cd $HOME
 git clone https://github.com/your-username/md2wiki.git www/js
 cd www/js
 npm install
 ```
 
-### 3. Create your production `.env` file
-```env
-WIKIMEDIA_CLIENT_ID=your_production_consumer_token
-WIKIMEDIA_CLIENT_SECRET=your_production_secret_token
-SESSION_SECRET=another_long_production_secret
-WIKIMEDIA_REDIRECT_URI=https://md2wiki.toolforge.org/api/auth/callback
-NODE_ENV=production
-PORT=8000
-```
+### 3. Create production `.env` file
+Include your Toolforge OAuth credentials, secret, and port details inside `www/js/.env`.
 
-### 4. Build and start the service
-Build the Next.js assets:
+### 4. Build and start
 ```bash
 npm run build
-```
-
-Configure Toolforge to start the Next.js production server:
-```bash
 toolforge webservice node18 start
 ```
-Toolforge automatically routes traffic to port `8000`. Next.js will serve the client pages and API routes at `https://md2wiki.toolforge.org/`.
+Traffic is automatically routed to `https://<tool-name>.toolforge.org/`.
 
 ---
 
-## 📂 Project Structure
+## 💻 Command Line Interface (CLI)
 
-* `src/core/`: The core conversion engine. Contains the TS parser and test files.
-* `src/app/`: The Next.js App Router containing:
-  * `api/`: API Route Handlers for SUL OAuth redirects, proxy readmes, and sandbox edits.
-  * `utils/`: File helper wrappers (session encryptor, raw README URL resolver).
-  * `globals.css` / `layout.tsx` / `page.tsx`: The styling baseline and frontend editor layout.
-* `toolinfo.json`: Toolhub scraper metadata.
+You can run the translator locally via command line to parse files:
 
----
-
-## 🧪 Running Unit Tests
+```bash
+npm run parse -- <path-to-markdown-file>
+```
 
-We use **Vitest** for running our unit tests. To verify the Markdown parser rules:
+For example, to convert `draft.md` and save the Wikitext output:
 ```bash
-npm run test
+npm run parse -- draft.md > draft.wiki
 ```
+Smart heading shifts and internal wiki link translation are enabled by default in CLI runs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "md2wiki",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Convert Markdown to MediaWiki Wikitext with SUL sandbox publishing.",
   "type": "module",
   "main": "./dist/parser.js",