oneclickpush 0.2.0 → 0.3.0

package/README.md

@@ -16,27 +16,28 @@ none of these, has zero dependencies and only uses built-in Node APIs + `git`.
 Deploy your build directory (e.g. `dist`) to the `gh-pages` branch:
 
 ```text
-$ cd dist
-$ npx oneclickpush
+$ npx oneclickpush dist
 ```
 
 ## CLI Usage
 
 ```text
-Usage: oneclickpush [options]
+Usage: oneclickpush <dir> [options]
 
 Replace the contents of a remote git branch with that of a local directory.
 
+Arguments:
+  dir                     Directory to deploy (required)
+
 Options:
-  -d, --dist <dir>        Directory to publish (default: ".")
-  -e, --exclude <glob>    Paths to leave out, relative to dist (default: "**/.DS_Store")
+  -e, --exclude <glob>    Paths to leave out, relative to dir (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")
+  -r, --remote <name|url> Remote name or repo URL to deploy 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
+  -l, --log-level <level> Output: silent, normal or verbose (default: "normal")
   -V, --version           Print version
   -h, --help              Show this help
 ```
@@ -45,27 +46,46 @@ Options:
 > `--exclude` takes glob patterns (`*`, `**`, `?`) and can be repeated. Patterns are matched against
 > the full path, so use `**/name` to match at any depth.
 
+### Log levels
+
+| Level     | Behavior                                                             |
+| --------- | -------------------------------------------------------------------- |
+| `silent`  | Prints nothing, not even errors. Check the exit code instead.        |
+| `normal`  | Prints the result and error messages (plus a spinner in a terminal). |
+| `verbose` | Also logs every git command to stderr and prints full errors.        |
+
+> [!WARNING]  
+> If your remote URL contains a token (e.g. `https://user:TOKEN@github.com/o/r.git`), git error
+> messages shown at `normal` and `verbose` may include it. Use `-l silent` in CI, or keep tokens out
+> of the URL with a credential helper.
+
 ### Examples
 
 ```bash
 # Preview what would be deployed without pushing
-npx oneclickpush -d build --dry-run
+npx oneclickpush build --dry-run
 
 # Custom branch and commit message
-npx oneclickpush -d public -b release -m "deploy: v1.0.0"
+npx oneclickpush public -b release -m "deploy: v1.0.0"
 
 # Exclude source maps and test files
-npx oneclickpush -d dist -e "**/*.map" -e "**/tests/**"
+npx oneclickpush 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
+npx oneclickpush dist -r upstream
+npx oneclickpush 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>"
+npx oneclickpush dist -a "Deploy Bot <bot@example.com>"
 
 # Force push fresh history
-npx oneclickpush -d dist --force
+npx oneclickpush dist --force
+
+# Silent output (useful in CI, check the exit code)
+npx oneclickpush dist -l silent
+
+# Log every git command
+npx oneclickpush dist -l verbose
 ```
 
 ## Programmatic API
@@ -73,15 +93,15 @@ npx oneclickpush -d dist --force
 You can also use `oneclickpush` as an ES module:
 
 ```bash
-# Install the library
+# Install
 npm i oneclickpush
 ```
 
 ```javascript
-import { publish } from 'oneclickpush'
+import { deploy } from 'oneclickpush'
 
-const changes = await publish({
-  dist: 'dist',
+const changes = await deploy({
+  dir: 'dist',
   exclude: ['**/.DS_Store', '**/*.map'],
   branch: 'gh-pages',
   message: 'Deploy updates',
@@ -89,29 +109,41 @@ const changes = await publish({
   author: 'Deploy Bot <bot@example.com>',
   force: false,
   dryRun: false,
-  verbose: false
+  logLevel: 'normal'
 })
 
 if (changes) {
-  console.log('Published changes:\n' + changes)
+  console.log('Deployed changes:\n' + changes)
 } else {
-  console.log('Nothing to publish')
+  console.log('Nothing to deploy')
 }
 ```
 
+The default values are also exported as `DEFAULTS`:
+
+```javascript
+import { DEFAULTS } from 'oneclickpush'
+
+console.log(DEFAULTS.branch) // "gh-pages"
+```
+
 ### 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                           |
+| Option     | Type                                | Default            | Description                                         |
+| ---------- | ----------------------------------- | ------------------ | --------------------------------------------------- |
+| `dir`      | `string`                            | - (required)       | Directory to deploy                                 |
+| `exclude`  | `string[]`                          | `["**/.DS_Store"]` | Paths to exclude relative to `dir`                  |
+| `branch`   | `string`                            | `"gh-pages"`       | Target git branch                                   |
+| `message`  | `string`                            | `"Updates"`        | Git commit message                                  |
+| `remote`   | `string`                            | `"origin"`         | Remote name or repository URL/path to deploy 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 |
+| `logLevel` | `"silent" \| "normal" \| "verbose"` | `"normal"`         | Only `"verbose"` has an effect: logs git commands   |
+
+> [!NOTE]  
+> The library never prints anything except at `"verbose"`. `"silent"` and `"normal"` only differ in
+> the CLI.
 
 ## How It Works
 
@@ -119,7 +151,7 @@ if (changes) {
    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)
+3. Clears the target branch index and stages the contents of `dir` (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.
@@ -130,12 +162,14 @@ if (changes) {
 
 ### 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.
+- The target branch is fully replaced with the contents of `dir` (WYSIWYG), and it's created if it
+  doesn't exist yet. If you need files like `.nojekyll` or `CNAME`, put them in `dir`, adding a
+  post-build step if your build tool wipes the directory.
+- Dotfiles are included by default, except `.DS_Store`. Use `-e` to exclude more, but note that it
+  replaces the default list, so repeat `-e "**/.DS_Store"` if you still want that file excluded.
+- When `--remote` is a repository URL or path, you don't need to run from inside a git repository.
+- In dry-run output, identical content moved to a new path appears as a rename (`R100`).
+- A directory starting with `-` must come after `--`, e.g. `oneclickpush -- -weird-dir`.
 
 ## License
 

package/cli.js

@@ -1,48 +1,67 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util'
 import { readFileSync } from 'node:fs'
-import { publish } from './index.js'
+import { deploy, DEFAULTS } from './index.js'
 
-const HELP = `Usage: oneclickpush [options]
+const HELP = `Usage: oneclickpush <dir> [options]
 
 Replace the contents of a remote git branch with that of a
 local directory.
 
+Arguments:
+  dir                     Directory to deploy (required)
+
 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")
+  -e, --exclude <glob>    Paths to leave out, relative to dir
+                          (default: "${DEFAULTS.exclude.join(', ')}")
+  -b, --branch <name>     Target branch (default: "${DEFAULTS.branch}")
+  -m, --message <msg>     Commit message (default: "${DEFAULTS.message}")
+  -r, --remote <name|url> Remote name or repo URL to deploy to
+                          (default: "${DEFAULTS.remote}")
   -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
+  -l, --log-level <level> Output: silent, normal or verbose
+                          (default: "${DEFAULTS.logLevel}")
   -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.`
+match at any depth.
+
+Log levels: "silent" prints nothing (check the exit code),
+"normal" prints the result and errors, "verbose" also logs git
+commands and full errors.`
+
+const LEVELS = ['silent', 'normal', 'verbose']
 
-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 }
+const { values: v, positionals } = (() => {
+  try {
+    return parseArgs({
+      allowPositionals: true,
+      options: {
+        exclude: { type: 'string', short: 'e', multiple: true, default: DEFAULTS.exclude },
+        branch: { type: 'string', short: 'b', default: DEFAULTS.branch },
+        message: { type: 'string', short: 'm', default: DEFAULTS.message },
+        remote: { type: 'string', short: 'r', default: DEFAULTS.remote },
+        author: { type: 'string', short: 'a' },
+        force: { type: 'boolean', short: 'f', default: DEFAULTS.force },
+        'dry-run': { type: 'boolean', short: 'n', default: DEFAULTS.dryRun },
+        'log-level': { type: 'string', short: 'l', default: DEFAULTS.logLevel },
+        version: { type: 'boolean', short: 'V', default: false },
+        help: { type: 'boolean', short: 'h', default: false }
+      }
+    })
+  } catch (/** @type {any} */ e) {
+    if (!e.code?.startsWith('ERR_PARSE_ARGS_')) throw e
+    // Keep only the first sentence, Node appends a long "-- " hint to some messages
+    const msg = e.message.split('. ')[0].replace(/\.$/, '')
+    console.error(`${msg}, run "oneclickpush --help" for usage`)
+    process.exit(1)
   }
-})
+})()
 
 if (v.help) {
   console.log(HELP)
@@ -55,27 +74,46 @@ if (v.version) {
   process.exit(0)
 }
 
-// Dead simple spinner (skipped when verbose or piped)
+if (positionals.length !== 1) {
+  console.error(
+    positionals.length === 0
+      ? 'Missing required argument <dir>, run "oneclickpush --help" for usage'
+      : 'Expected exactly one directory, run "oneclickpush --help" for usage'
+  )
+  process.exit(1)
+}
+const dir = positionals[0]
+
+const level = /** @type {import('./index.js').OcpOptionsLogLevel} */ (v['log-level'])
+if (!LEVELS.includes(level)) {
+  console.error(`Invalid --log-level "${level}", expected one of: ${LEVELS.join(', ')}`)
+  process.exit(1)
+}
+
+// Dead simple spinner (normal level, TTY only)
 const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
 let i = 0
 const spin =
-  process.stderr.isTTY && !v.verbose
+  process.stderr.isTTY && level === 'normal'
     ? 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'] })
+  const changes = await deploy({ ...v, dir, logLevel: level, dryRun: v['dry-run'] })
   stop()
-  console.log(
-    !changes
-      ? 'Nothing to publish'
-      : v['dry-run']
-        ? `Dry run, would publish:\n${changes}`
-        : 'Published'
-  )
+  if (level !== 'silent') {
+    console.log(
+      !changes
+        ? 'Nothing to deploy'
+        : v['dry-run']
+          ? `Dry run, would deploy:\n${changes}`
+          : 'Deployed!'
+    )
+  }
 } catch (/** @type {any} */ e) {
   stop()
-  console.error(v.verbose ? e : e.message)
+  if (level === 'verbose') console.error(e)
+  else if (level === 'normal') console.error(e.message)
   process.exit(1)
 }

package/index.d.ts

@@ -1,10 +1,21 @@
-export type OneclickpushOptions = {
+export type OcpOptionsLogLevel = 'silent' | 'normal' | 'verbose'
+/** @typedef {'silent' | 'normal' | 'verbose'} OcpOptionsLogLevel */
+export declare const DEFAULTS: {
+  exclude: string[]
+  branch: string
+  message: string
+  remote: string
+  force: boolean
+  dryRun: boolean
+  logLevel: OcpOptionsLogLevel
+}
+export type OcpOptions = {
   /**
-   * Directory to publish
+   * Directory to deploy (required)
    */
-  dist?: string
+  dir: string
   /**
-   * Paths to leave out, relative to dist (default: `**\/.DS_Store`)
+   * Paths to leave out, relative to dir (default: `**\/.DS_Store`)
    */
   exclude?: string[]
   /**
@@ -32,30 +43,30 @@ export type OneclickpushOptions = {
    */
   dryRun?: boolean
   /**
-   * Log git commands
+   * Only "verbose" logs (git commands, to stderr)
    */
-  verbose?: boolean
+  logLevel?: OcpOptionsLogLevel
 }
 /**
- * @typedef {object} OneclickpushOptions
- * @prop {string} [dist="."] Directory to publish
- * @prop {string[]} [exclude] Paths to leave out, relative to dist (default: `**\/.DS_Store`)
+ * @typedef {object} OcpOptions
+ * @prop {string} dir Directory to deploy (required)
+ * @prop {string[]} [exclude] Paths to leave out, relative to dir (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
+ * @prop {OcpOptionsLogLevel} [logLevel="normal"] Only "verbose" logs (git commands, to stderr)
  */
 /**
  * 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
+ * @param {OcpOptions} options
  * @returns {Promise<string>}
  */
-export declare function publish({
-  dist,
+export declare function deploy({
+  dir,
   exclude,
   branch,
   message,
@@ -63,5 +74,5 @@ export declare function publish({
   author,
   force,
   dryRun,
-  verbose
-}: OneclickpushOptions): Promise<string>
+  logLevel
+}: OcpOptions): Promise<string>

package/index.js

@@ -4,37 +4,50 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 
+/** @typedef {'silent' | 'normal' | 'verbose'} OcpOptionsLogLevel */
+
+export const DEFAULTS = {
+  exclude: ['**/.DS_Store'],
+  branch: 'gh-pages',
+  message: 'Updates',
+  remote: 'origin',
+  force: false,
+  dryRun: false,
+  logLevel: /** @type {OcpOptionsLogLevel} */ ('normal')
+}
+
 /**
- * @typedef {object} OneclickpushOptions
- * @prop {string} [dist="."] Directory to publish
- * @prop {string[]} [exclude] Paths to leave out, relative to dist (default: `**\/.DS_Store`)
+ * @typedef {object} OcpOptions
+ * @prop {string} dir Directory to deploy (required)
+ * @prop {string[]} [exclude] Paths to leave out, relative to dir (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
+ * @prop {OcpOptionsLogLevel} [logLevel="normal"] Only "verbose" logs (git commands, to stderr)
  */
 
 /**
  * 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
+ * @param {OcpOptions} options
  * @returns {Promise<string>}
  */
-export async function publish({
-  dist = '.',
-  exclude = ['**/.DS_Store'],
-  branch = 'gh-pages',
-  message = 'Updates',
-  remote = 'origin',
+export async function deploy({
+  dir,
+  exclude = DEFAULTS.exclude,
+  branch = DEFAULTS.branch,
+  message = DEFAULTS.message,
+  remote = DEFAULTS.remote,
   author,
-  force = false,
-  dryRun = false,
-  verbose = false
+  force = DEFAULTS.force,
+  dryRun = DEFAULTS.dryRun,
+  logLevel = DEFAULTS.logLevel
 }) {
-  dist = resolve(dist)
+  if (!dir) throw new Error('dir is required')
+  dir = resolve(dir)
   const run = promisify(execFile)
 
   // Env vars beat git config, so this also overrides any identity already set in CI
@@ -53,8 +66,9 @@ export async function publish({
 
   /** @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()
+    if (logLevel === 'verbose') console.error(`$ git ${args.join(' ')}`)
+    const { stdout } = await run('git', args, { cwd, env: { ...process.env, ...env } })
+    return stdout.trim()
   }
 
   // A remote name resolves to its url; anything else is used as a url or path as-is
@@ -82,21 +96,21 @@ export async function publish({
       await git(['remote', 'add', 'origin', url], tmp)
     }
 
-    // Empty the index, then stage everything from dist except excluded paths
+    // Empty the index, then stage everything from dir except excluded paths
     await git(['read-tree', '--empty'], tmp)
     await git(
       [
         '--git-dir',
         join(tmp, '.git'),
         '--work-tree',
-        dist,
+        dir,
         'add',
         '--force',
         '--',
         '.',
         ...exclude.map((p) => `:(exclude,glob)${p}`)
       ],
-      dist
+      dir
     )
 
     const status = await git(['diff', '--cached', '--name-status'], tmp)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oneclickpush",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "One-click GitHub Pages deployer",
   "author": "Jason Lee <jason@zerodevx.com>",
   "scripts": {
@@ -33,6 +33,7 @@
   "keywords": [
     "one-click",
     "gh-pages",
-    "deploy"
+    "deploy",
+    "cli"
   ]
 }