oneclickpush 0.1.0-next.1 → 0.2.0

package/README.md

@@ -1,3 +1,142 @@
 # oneclickpush
 
 > 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 built-in Node APIs + `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")
+  -r, --remote <name|url> Remote name or repo URL to publish to (default: "origin")
+  -a, --author <author>   Commit author, as "Name <email>"
+  -f, --force             Force push new commit 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/**"
+
+# Deploy to a different remote or repository URL
+npx oneclickpush -d dist -r upstream
+npx oneclickpush -d dist -r git@github.com:user/repo.git
+
+# Set commit author (useful in CI environments)
+npx oneclickpush -d dist -a "Deploy Bot <bot@example.com>"
+
+# 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',
+  remote: 'origin',
+  author: 'Deploy Bot <bot@example.com>',
+  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                                  |
+| `remote`  | `string`   | `"origin"`         | Remote name or repository URL/path to publish to    |
+| `author`  | `string`   | —                  | Commit author and committer, as `"Name <email>"`    |
+| `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 target repository URL from git remote configuration or uses the provided remote
+   URL/path directly.
+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` (minus `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 the remote repository.
+5. Cleans up the temporary directory.
+
+> [!WARNING]  
+> Requires Node 18.3+ and Git 2.28+.
+
+### Notes
+
+- Dotfiles (except `.DS_Store`) are 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.
+- When `--remote` is a repository URL or path, running from within an existing git repository is not
+  required.
+
+## License
+
+ISC

package/cli.js

@@ -1,3 +1,81 @@
 #!/usr/bin/env node
+import { parseArgs } from 'node:util'
+import { readFileSync } from 'node:fs'
+import { publish } from './index.js'
 
-console.log('noop')
+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")
+  -r, --remote <name|url> Remote name or repo URL to publish to
+                          (default: "origin")
+  -a, --author <author>   Commit author, as "Name <email>"
+  -f, --force             Force push new commit 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' },
+    message: { type: 'string', short: 'm', default: 'Updates' },
+    remote: { type: 'string', short: 'r', default: 'origin' },
+    author: { type: 'string', short: 'a' },
+    force: { type: 'boolean', short: 'f', default: false },
+    '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,67 @@
+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
+  /**
+   * Remote name of the current repo, or a repository URL or path
+   */
+  remote?: string
+  /**
+   * Commit author and committer as "Name <email>"
+   */
+  author?: string
+  /**
+   * Force push new commit 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 {string} [remote="origin"] Remote name of the current repo, or a repository URL or path
+ * @prop {string} [author] Commit author and committer as "Name <email>"
+ * @prop {boolean} [force=false] Force push new commit 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,
+  remote,
+  author,
+  force,
+  dryRun,
+  verbose
+}: OneclickpushOptions): Promise<string>

package/index.js

@@ -1 +1,111 @@
-console.log('noop')
+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 {string} [remote="origin"] Remote name of the current repo, or a repository URL or path
+ * @prop {string} [author] Commit author and committer as "Name <email>"
+ * @prop {boolean} [force=false] Force push new commit 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',
+  remote = 'origin',
+  author,
+  force = false,
+  dryRun = false,
+  verbose = false
+}) {
+  dist = resolve(dist)
+  const run = promisify(execFile)
+
+  // Env vars beat git config, so this also overrides any identity already set in CI
+  /** @type {Record<string, string>} */
+  let identity = {}
+  if (author) {
+    const m = /^(.+?)\s*<(.+)>$/.exec(author)
+    if (!m) throw new Error('--author must look like "Name <email>"')
+    identity = {
+      GIT_AUTHOR_NAME: m[1],
+      GIT_AUTHOR_EMAIL: m[2],
+      GIT_COMMITTER_NAME: m[1],
+      GIT_COMMITTER_EMAIL: m[2]
+    }
+  }
+
+  /** @type {(args: string[], cwd?: string, env?: Record<string, string>) => Promise<string>} */
+  const git = async (args, cwd, env) => {
+    if (verbose) console.error(`$ git ${args.join(' ')}`)
+    return (await run('git', args, { cwd, env: { ...process.env, ...env } })).stdout.trim()
+  }
+
+  // A remote name resolves to its url; anything else is used as a url or path as-is
+  let url = remote
+  try {
+    url = await git(['remote', 'get-url', remote])
+  } catch {
+    if (/^[\w-]+$/.test(remote)) throw new Error(`Remote "${remote}" not found`)
+  }
+
+  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, identity)
+    await git(['push', '-q', ...(force ? ['--force'] : []), 'origin', branch], tmp)
+    return status
+  } finally {
+    await rm(tmp, { recursive: true, force: true })
+  }
+}

package/package.json

@@ -1,28 +1,33 @@
 {
   "name": "oneclickpush",
-  "version": "0.1.0-next.1",
+  "version": "0.2.0",
   "description": "One-click GitHub Pages deployer",
   "author": "Jason Lee <jason@zerodevx.com>",
   "scripts": {
-    "lint": "prettier --check . && eslint && npx publint",
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "dependencies": {
-    "zx": "^8.8.5"
+    "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"
+    "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": [