oneclickpush 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Jason Lee <jason@zerodevx.com>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# oneclickpush
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> One-click GitHub Pages deployer
+
+Replace the contents of a remote git branch (like `gh-pages`) with the contents of a local directory
+in one command.
+
+[`gh-pages`](https://github.com/tschaub/gh-pages) is
+[complicated](https://github.com/tschaub/gh-pages/tree/main/lib),
+[buggy](https://github.com/tschaub/gh-pages/issues), and
+[unmaintained](https://github.com/tschaub/gh-pages/issues/657#issue-4979248775); `oneclickpush` is
+none of these, has zero dependencies and only uses Node native functions + `git`.
+
+## Quick Start
+
+Deploy your build directory (e.g. `dist`) to the `gh-pages` branch:
+
+```text
+$ cd dist
+$ npx oneclickpush
+```
+
+## CLI Usage
+
+```text
+Usage: oneclickpush [options]
+
+Replace the contents of a remote git branch with that of a local directory.
+
+Options:
+  -d, --dist <dir>        Directory to publish (default: ".")
+  -e, --exclude <glob>    Paths to leave out, relative to dist (default: "**/.DS_Store")
+  -b, --branch <name>     Target branch (default: "gh-pages")
+  -m, --message <msg>     Commit message (default: "Updates")
+  -f, --force             Force push with no history
+  -n, --dry-run           Show what would change, without committing or pushing
+  -v, --verbose           Log git commands
+  -V, --version           Print version
+  -h, --help              Show this help
+```
+
+> [!TIP]  
+> `--exclude` takes glob patterns (`*`, `**`, `?`) and can be repeated. Patterns are matched against
+> the full path, so use `**/name` to match at any depth.
+
+### Examples
+
+```bash
+# Preview what would be deployed without pushing
+npx oneclickpush -d build --dry-run
+
+# Custom branch and commit message
+npx oneclickpush -d public -b release -m "deploy: v1.0.0"
+
+# Exclude source maps and test files
+npx oneclickpush -d dist -e "**/*.map" -e "**/tests/**"
+
+# Force push fresh history
+npx oneclickpush -d dist --force
+```
+
+## Programmatic API
+
+You can also use `oneclickpush` as an ES module:
+
+```bash
+# Install the library
+npm i oneclickpush
+```
+
+```javascript
+import { publish } from 'oneclickpush'
+
+const changes = await publish({
+  dist: 'dist',
+  exclude: ['**/.DS_Store', '**/*.map'],
+  branch: 'gh-pages',
+  message: 'Deploy updates',
+  force: false,
+  dryRun: false,
+  verbose: false
+})
+
+if (changes) {
+  console.log('Published changes:\n' + changes)
+} else {
+  console.log('Nothing to publish')
+}
+```
+
+### Options
+
+| Option    | Type       | Default            | Description                                         |
+| --------- | ---------- | ------------------ | --------------------------------------------------- |
+| `dist`    | `string`   | `"."`              | Directory to publish                                |
+| `exclude` | `string[]` | `["**/.DS_Store"]` | Paths to exclude relative to `dist`                 |
+| `branch`  | `string`   | `"gh-pages"`       | Target git branch                                   |
+| `message` | `string`   | `"Updates"`        | Git commit message                                  |
+| `force`   | `boolean`  | `false`            | Force push fresh commit with no previous history    |
+| `dryRun`  | `boolean`  | `false`            | Return staged changes without committing or pushing |
+| `verbose` | `boolean`  | `false`            | Log executed git commands                           |
+
+## How It Works
+
+1. Resolves the remote origin repository URL from local git configuration.
+2. Creates an isolated temporary directory and fetches the target branch (or initializes it if it
+   doesn't exist).
+3. Clears the target branch index and stages the contents of `dist` (less `exclude` patterns)
+   directly via Git `work-tree`.
+4. Checks for differences (`git diff --cached --name-status`). If there are changes, commits and
+   pushes back to `origin`.
+5. Cleans up the temporary directory.
+
+> [!WARNING]  
+> Requires Node 18.3+ and Git 2.28+.
+
+### Notes
+
+- Dot files included by default; use `-e` to exclude.
+- Contents in target branch are emptied and replaced with the contents of `dist` (WYSIWYG).
+- If `.nojekyll` or `CNAME` files are required, add them to `dist`; use a post-build step if needed.
+- If the target branch does not exist, it will be created.
+
+## License
+
+ISC

package/cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util'
+import { readFileSync } from 'node:fs'
+import { publish } from './index.js'
+
+const HELP = `Usage: oneclickpush [options]
+
+Replace the contents of a remote git branch with that of a 
+local directory.
+
+Options:
+  -d, --dist <dir>        Directory to publish (default: ".")
+  -e, --exclude <glob>    Paths to leave out, relative to dist
+                          (default: "**/.DS_Store")
+  -b, --branch <name>     Target branch (default: "gh-pages")
+  -m, --message <msg>     Commit message (default: "Updates")
+  -f, --force             Force push with no history
+  -n, --dry-run           Show what would change, without 
+                          committing or pushing
+  -v, --verbose           Log git commands
+  -V, --version           Print version
+  -h, --help              Show this help
+
+--exclude takes glob patterns (*, **, ?) and can be repeated. 
+Patterns are matched against the full path, so use **/name to 
+match at any depth.`
+
+const { values: v } = parseArgs({
+  options: {
+    dist: { type: 'string', short: 'd', default: '.' },
+    exclude: { type: 'string', short: 'e', multiple: true, default: ['**/.DS_Store'] },
+    branch: { type: 'string', short: 'b', default: 'gh-pages' },
+    force: { type: 'boolean', short: 'f', default: false },
+    message: { type: 'string', short: 'm', default: 'Updates' },
+    'dry-run': { type: 'boolean', short: 'n', default: false },
+    verbose: { type: 'boolean', short: 'v', default: false },
+    version: { type: 'boolean', short: 'V', default: false },
+    help: { type: 'boolean', short: 'h', default: false }
+  }
+})
+
+if (v.help) {
+  console.log(HELP)
+  process.exit(0)
+}
+
+if (v.version) {
+  const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'))
+  console.log(pkg.version)
+  process.exit(0)
+}
+
+// Dead simple spinner (skipped when verbose or piped)
+const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+let i = 0
+const spin =
+  process.stderr.isTTY && !v.verbose
+    ? setInterval(() => process.stderr.write(`\r${frames[i++ % frames.length]}`), 100)
+    : null
+const stop = () => spin && (clearInterval(spin), process.stderr.write('\r \r'))
+
+try {
+  const changes = await publish({ ...v, dryRun: v['dry-run'] })
+  stop()
+  console.log(
+    !changes
+      ? 'Nothing to publish'
+      : v['dry-run']
+        ? `Dry run, would publish:\n${changes}`
+        : 'Published'
+  )
+} catch (/** @type {any} */ e) {
+  stop()
+  console.error(v.verbose ? e : e.message)
+  process.exit(1)
+}

package/index.d.ts

@@ -0,0 +1,55 @@
+export type OneclickpushOptions = {
+  /**
+   * Directory to publish
+   */
+  dist?: string
+  /**
+   * Paths to leave out, relative to dist (default: `**\/.DS_Store`)
+   */
+  exclude?: string[]
+  /**
+   * Target branch
+   */
+  branch?: string
+  /**
+   * Commit message
+   */
+  message?: string
+  /**
+   * Force push with no history
+   */
+  force?: boolean
+  /**
+   * Show what would change, without committing or pushing
+   */
+  dryRun?: boolean
+  /**
+   * Log git commands
+   */
+  verbose?: boolean
+}
+/**
+ * @typedef {object} OneclickpushOptions
+ * @prop {string} [dist="."] Directory to publish
+ * @prop {string[]} [exclude] Paths to leave out, relative to dist (default: `**\/.DS_Store`)
+ * @prop {string} [branch="gh-pages"] Target branch
+ * @prop {string} [message="Updates"] Commit message
+ * @prop {boolean} [force=false] Force push with no history
+ * @prop {boolean} [dryRun=false] Show what would change, without committing or pushing
+ * @prop {boolean} [verbose=false] Log git commands
+ */
+/**
+ * Replace the contents of a git branch with the contents of a directory.
+ * Returns the staged changes as `git diff --name-status` text or "" if nothing changed.
+ * @param {OneclickpushOptions} options
+ * @returns {Promise<string>}
+ */
+export declare function publish({
+  dist,
+  exclude,
+  branch,
+  message,
+  force,
+  dryRun,
+  verbose
+}: OneclickpushOptions): Promise<string>

package/index.js

@@ -0,0 +1,86 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+/**
+ * @typedef {object} OneclickpushOptions
+ * @prop {string} [dist="."] Directory to publish
+ * @prop {string[]} [exclude] Paths to leave out, relative to dist (default: `**\/.DS_Store`)
+ * @prop {string} [branch="gh-pages"] Target branch
+ * @prop {string} [message="Updates"] Commit message
+ * @prop {boolean} [force=false] Force push with no history
+ * @prop {boolean} [dryRun=false] Show what would change, without committing or pushing
+ * @prop {boolean} [verbose=false] Log git commands
+ */
+
+/**
+ * Replace the contents of a git branch with the contents of a directory.
+ * Returns the staged changes as `git diff --name-status` text or "" if nothing changed.
+ * @param {OneclickpushOptions} options
+ * @returns {Promise<string>}
+ */
+export async function publish({
+  dist = '.',
+  exclude = ['**/.DS_Store'],
+  branch = 'gh-pages',
+  message = 'Updates',
+  force = false,
+  dryRun = false,
+  verbose = false
+}) {
+  dist = resolve(dist)
+  const run = promisify(execFile)
+
+  /** @type {(args: string[], cwd?: string) => Promise<string>} */
+  const git = async (args, cwd) => {
+    if (verbose) console.error(`$ git ${args.join(' ')}`)
+    return (await run('git', args, { cwd })).stdout.trim()
+  }
+
+  const url = await git(['config', '--get', 'remote.origin.url'])
+  const tmp = await mkdtemp(join(tmpdir(), 'oneclickpush-'))
+
+  try {
+    // Reuse existing branch history unless forcing; otherwise start fresh
+    let cloned = false
+    if (!force) {
+      try {
+        await git(['clone', '--branch', branch, '--single-branch', '--depth', '1', url, tmp])
+        cloned = true
+        // eslint-disable-next-line no-empty
+      } catch {}
+    }
+    if (!cloned) {
+      await git(['init', '-q', '-b', branch], tmp)
+      await git(['remote', 'add', 'origin', url], tmp)
+    }
+
+    // Empty the index, then stage everything from dist except excluded paths
+    await git(['read-tree', '--empty'], tmp)
+    await git(
+      [
+        '--git-dir',
+        join(tmp, '.git'),
+        '--work-tree',
+        dist,
+        'add',
+        '--force',
+        '--',
+        '.',
+        ...exclude.map((p) => `:(exclude,glob)${p}`)
+      ],
+      dist
+    )
+
+    const status = await git(['diff', '--cached', '--name-status'], tmp)
+    if (!status || dryRun) return status
+
+    await git(['commit', '-q', '-m', message], tmp)
+    await git(['push', '-q', ...(force ? ['--force'] : []), 'origin', branch], tmp)
+    return status
+  } finally {
+    await rm(tmp, { recursive: true, force: true })
+  }
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "oneclickpush",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "One-click GitHub Pages deployer",
+  "author": "Jason Lee <jason@zerodevx.com>",
+  "scripts": {
+    "prepublishOnly": "npm run lint",
+    "emit": "tsc index.js -d --emitDeclarationOnly --allowJs && prettier --write index.d.ts",
+    "lint": "npm run emit && prettier --check . && eslint && npx publint",
+    "test": "node --test"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.12.0",
+    "globals": "^17.13.0",
+    "prettier": "^3.9.10",
+    "typescript": "^7.0.2"
+  },
+  "type": "module",
+  "exports": "./index.js",
+  "types": "./index.d.ts",
+  "bin": "cli.js",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "cli.js"
+  ],
+  "engines": {
+    "node": ">=18.3.0"
+  },
+  "license": "ISC",
+  "repository": "github:zerodevx/oneclickpush",
+  "keywords": [
+    "one-click",
+    "gh-pages",
+    "deploy"
+  ]
+}