@peterseibel/hug 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:registry.npmjs.org)",
+      "WebFetch(domain:script.googleapis.com)",
+      "WebFetch(domain:oauth2.googleapis.com)",
+      "Bash(./node_modules/.bin/clasp clone:*)",
+      "WebFetch(domain:developers.google.com)",
+      "WebFetch(domain:github.com)",
+      "WebSearch",
+      "WebFetch(domain:www.npmjs.com)",
+      "Bash(./node_modules/.bin/clasp --version && ./node_modules/.bin/clasp deploy --help 2>&1; ./node_modules/.bin/clasp redeploy --help 2>&1)",
+      "Bash(./node_modules/.bin/clasp list-versions:*)",
+      "Bash(./node_modules/.bin/clasp create-version:*)",
+      "Bash(./node_modules/.bin/clasp list-deployments:*)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(gh api:*)"
+    ]
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,72 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`hug` is a lightweight bash CLI that wraps [clasp](https://github.com/google/clasp) to provide opinionated project management for Google Apps Script projects. It handles project creation (from templates or by importing existing projects), forking projects for branch-based workflows, and a push→version→deploy workflow.
+
+## Project structure
+
+```
+bin/hug              # CLI entry point (bash, subcommand dispatch)
+lib/common.sh        # Shared functions (clasp resolution, deployment helpers)
+templates/blank/     # Minimal Apps Script project template
+templates/webapp/    # Webapp template (doGet + index.html)
+package.json         # npm package with bin field pointing to bin/hug
+```
+
+## Key commands
+
+```bash
+./bin/hug init [--template blank|webapp] [name]   # create new project from template
+./bin/hug init --scriptId <id> [name]             # import existing project
+./bin/hug fork                                    # new Apps Script project from current code
+./bin/hug config set KEY=VALUE                    # manage config.js
+./bin/hug deploy "description"                    # push + version + deploy
+./bin/hug deploy --rollback <version>             # roll back
+./bin/hug push / pull [-f] / open                 # clasp passthrough (pull checks git status)
+./bin/hug versions / deployments                  # list versions/deployments
+```
+
+## Design decisions
+
+### Deployments
+
+Apps Script deployments are mainly useful for web apps (stable URL) and API
+executables. Hug takes an opinionated approach: one deployment per project,
+managed via `hug deploy`. If multiple deployments exist (e.g. created directly
+via clasp), hug handles them gracefully — `select_deployment` in `common.sh`
+prompts the user to pick one. But hug doesn't provide commands to create or
+delete individual deployments.
+
+Multiple deployments on a single script share script properties, so they all
+operate on the same underlying data (e.g. the same spreadsheet). This makes
+them suitable for variant UIs against the same data, but not for dev/prod
+separation. For dev/prod, use `hug fork` + git branches instead — each branch
+gets its own script project with independent properties and deployments.
+
+### Config
+
+`hug config` manages a local `config.js` file (JS constants object) that gets
+pushed with the code. This avoids the heavy GCP setup required by `clasp run`
+for setting script properties. Config values are in source/git, which is fine
+for spreadsheet IDs etc. but not for secrets. Each git branch can have different
+config values, pairing well with `hug fork`.
+
+### Auth
+
+Hug does not wrap `clasp login`. Auth credentials are stored globally in
+`~/.clasprc.json` and persist across projects. Instead, all clasp invocations
+go through `run_clasp` which detects auth errors and suggests running
+`npx clasp login`.
+
+## Development
+
+There is no build step or test suite. The CLI is pure bash. To test locally:
+
+```bash
+./bin/hug --help
+```
+
+clasp is a dependency (`@google/clasp`). The CLI finds it at `./node_modules/.bin/clasp` first, then falls back to a global `clasp`.

package/DEVELOPMENT.md

@@ -0,0 +1,86 @@
+# Development
+
+## Local testing
+
+There's no build step or test suite. To test locally, run commands directly:
+
+```bash
+./bin/hug --help
+./bin/hug init --template webapp /tmp/test-project
+```
+
+To test as if installed globally, link the package:
+
+```bash
+npm link
+hug --help
+```
+
+To unlink:
+
+```bash
+npm unlink -g @peterseibel/hug
+```
+
+## Project structure
+
+- `bin/hug` — CLI entry point (bash). All subcommands live here.
+- `lib/common.sh` — Shared functions sourced by `bin/hug`.
+- `templates/` — Project templates copied by `hug init`.
+- `plans/` — Implementation plans. `plans/done/` holds completed plans.
+
+## Publishing to npm
+
+The package is scoped as `@peterseibel/hug`.
+
+### First time
+
+Make sure you're logged in to npm and that your scope is configured:
+
+```bash
+npm login
+```
+
+Scoped packages are private by default. To publish as public:
+
+```bash
+npm publish --access public
+```
+
+### Subsequent releases
+
+1. Bump the version in `package.json` (or use `npm version`):
+
+   ```bash
+   npm version patch   # 0.1.0 -> 0.1.1
+   npm version minor   # 0.1.1 -> 0.2.0
+   npm version major   # 0.2.0 -> 1.0.0
+   ```
+
+   `npm version` creates a git commit and tag automatically.
+
+2. Publish:
+
+   ```bash
+   npm publish
+   ```
+
+3. Push the version commit and tag:
+
+   ```bash
+   git push && git push --tags
+   ```
+
+## Dependencies
+
+The only runtime dependency is `@google/clasp`. It's listed in `package.json`
+so it gets installed when users `npm install -g @peterseibel/hug`.
+
+In user projects created by `hug init`, clasp is installed as a dev dependency
+via `ensure_clasp` in `lib/common.sh`.
+
+## Auth
+
+Clasp credentials live in `~/.clasprc.json` (global, not per-project). To test
+commands that talk to the Apps Script API, you need to have run `clasp login`
+at least once.

package/README.md

@@ -0,0 +1,111 @@
+# hug
+
+A lightweight wrapper around [clasp](https://github.com/google/clasp) for managing Google Apps Script projects.
+
+## Install
+
+```bash
+npm install -g @peterseibel/hug
+```
+
+Or clone this repo and link it:
+
+```bash
+git clone <repo-url> && cd hug
+npm install && npm link
+```
+
+## Prerequisites
+
+You need to be logged in to clasp:
+
+```bash
+npx clasp login
+```
+
+## Commands
+
+### Create a new project
+
+```bash
+hug init my-app                         # blank project
+hug init --template webapp my-app       # webapp with doGet + index.html
+```
+
+This creates the directory, copies template files, installs clasp, and creates the Apps Script project.
+
+### Import an existing project
+
+```bash
+hug init --scriptId <scriptId> my-project
+```
+
+Imports an existing Apps Script project into a new directory and sets up npm/clasp.
+
+### Fork a project
+
+```bash
+hug fork
+```
+
+Creates a new Apps Script project from the current local code. Useful with git branches — fork on a branch to get a separate Apps Script project you can develop against independently.
+
+### Configure
+
+```bash
+hug config                          # list config values
+hug config set SPREADSHEET_ID=1Bx.. # set a value
+hug config set FOO=bar BAZ=qux      # set multiple values
+hug config unset FOO                # remove a value
+```
+
+Manages a `config.js` file that gets pushed with your code. Apps Script code can access values via `CONFIG.SPREADSHEET_ID`, etc. Useful for pointing different branches/forks at different resources.
+
+Note: config values are stored in source. Don't put secrets here.
+
+### Push / Pull / Open
+
+```bash
+hug push          # push local files to Apps Script
+hug pull          # pull remote files (refuses if uncommitted changes)
+hug pull -f       # pull even with uncommitted changes
+hug open          # open in the Apps Script editor
+```
+
+### Deploy
+
+```bash
+hug deploy "description of changes"
+```
+
+Pushes code, creates a version, and updates the existing deployment (or creates one if none exists).
+
+### Roll back
+
+```bash
+hug deploy --rollback <versionNumber>
+```
+
+### List versions and deployments
+
+```bash
+hug versions
+hug deployments
+```
+
+## Templates
+
+- **blank** — minimal `appsscript.json` + empty `Code.js`
+- **webapp** — `doGet()` serving an `index.html`, with webapp config in the manifest
+
+## Branch-per-environment pattern
+
+Use `hug fork` with git branches to maintain separate Apps Script projects:
+
+```bash
+git checkout -b staging
+hug fork                              # new Apps Script project, updates .clasp.json
+hug config set SPREADSHEET_ID=1Bx..   # point at a staging spreadsheet
+hug deploy                            # deploys to the staging project
+git checkout main                     # .clasp.json and config.js switch back to production
+```

package/bin/hug

@@ -0,0 +1,458 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+HUG_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+source "$HUG_ROOT/lib/common.sh"
+
+VERSION="0.1.0"
+
+usage() {
+  cat <<EOF
+hug $VERSION — a lightweight wrapper around clasp
+
+Usage: hug <command> [options]
+
+Project commands:
+  init [--template blank|webapp] [name]   Create a new project from a template
+  init --scriptId <id> [name]             Import an existing Apps Script project
+  fork                                    Create a new Apps Script project from current code
+
+Development commands:
+  push                Push local files to Apps Script
+  pull [-f|--force]   Pull remote files (refuses if uncommitted changes)
+  open                Open the project in the Apps Script editor
+
+Configuration:
+  config                        List config values
+  config set KEY=VALUE ...      Set config values (writes config.js)
+  config unset KEY ...          Remove config values
+
+Deployment commands:
+  deploy [description]          Push, version, and update deployment
+  deploy --rollback <version>   Roll back to a previous version
+  versions                      List versions
+  deployments                   List deployments
+
+Run 'hug <command> --help' for details on a specific command.
+EOF
+}
+
+# ─── init ────────────────────────────────────────────────────────────────────
+
+cmd_init() {
+  local template="" name="" script_id="" force=false
+
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --template) template="$2"; shift 2 ;;
+      --scriptId) script_id="$2"; shift 2 ;;
+      -f|--force) force=true; shift ;;
+      --help)
+        echo "Usage: hug init [--template blank|webapp] [-f|--force] [name]"
+        echo "       hug init --scriptId <id> [-f|--force] [name]"
+        echo ""
+        echo "Creates a new Apps Script project. If name is given, creates a directory."
+        echo "Refuses if the directory already exists (use -f to override)."
+        echo ""
+        echo "Options:"
+        echo "  --template   Start from a template: blank (default), webapp"
+        echo "  --scriptId   Import an existing Apps Script project by ID"
+        echo "  -f, --force  Use an existing directory even if it already exists"
+        return 0 ;;
+      *) name="$1"; shift ;;
+    esac
+  done
+
+  # Validate flags
+  if [ -n "$script_id" ] && [ -n "$template" ]; then
+    echo "Error: --scriptId and --template are mutually exclusive" >&2
+    return 1
+  fi
+
+  local project_dir="."
+  if [ -n "$name" ]; then
+    project_dir="$name"
+    if [ -d "$project_dir" ] && [ "$force" = false ]; then
+      echo "Error: directory '$project_dir' already exists. Use -f to override." >&2
+      return 1
+    fi
+    mkdir -p "$project_dir"
+  elif [ -f .clasp.json ] && [ "$force" = false ]; then
+    echo "Error: .clasp.json already exists in this directory. Use -f to override." >&2
+    return 1
+  fi
+
+  cd "$project_dir"
+  ensure_clasp
+  local clasp
+  clasp=$(find_clasp)
+
+  if [ -n "$script_id" ]; then
+    # Import mode: clone an existing project
+    echo "Importing project $script_id..."
+    run_clasp "$clasp" clone "$script_id"
+
+    echo ""
+    echo "Project imported. Next steps:"
+    echo "  hug pull        Fetch the latest code"
+    echo "  hug open        Open in the Apps Script editor"
+  else
+    # Template mode: create a new project
+    template="${template:-blank}"
+
+    local template_dir="$HUG_ROOT/templates/$template"
+    if [ ! -d "$template_dir" ]; then
+      echo "Error: unknown template '$template'. Available: blank, webapp" >&2
+      return 1
+    fi
+
+    echo "Copying $template template..."
+    cp -r "$template_dir"/* ./
+
+    local title="${name:-$(basename "$(pwd)")}"
+    local type="standalone"
+    if [ "$template" = "webapp" ]; then
+      type="webapp"
+    fi
+
+    echo "Creating Apps Script project '$title' (type: $type)..."
+    run_clasp "$clasp" create --type "$type" --title "$title"
+
+    echo ""
+    echo "Project ready. Next steps:"
+    echo "  hug push        Push code to Apps Script"
+    echo "  hug open        Open in the Apps Script editor"
+    if [ "$template" = "webapp" ]; then
+      echo "  hug deploy      Push, version, and create a deployment"
+    fi
+  fi
+}
+
+# ─── fork ─────────────────────────────────────────────────────────────────────
+
+cmd_fork() {
+  local force=false
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      -f|--force) force=true; shift ;;
+      --help)
+        echo "Usage: hug fork [-f|--force]"
+        echo ""
+        echo "Creates a new Apps Script project from the current local code."
+        echo "Replaces .clasp.json with a new project, then pushes code to it."
+        echo ""
+        echo "Refuses if the current project is container-bound (use -f to override)."
+        echo ""
+        echo "Useful with git branches: fork on a branch to get a separate"
+        echo "Apps Script project for each branch."
+        return 0 ;;
+      *) shift ;;
+    esac
+  done
+
+  if [ ! -f .clasp.json ]; then
+    echo "Error: no .clasp.json found. Run 'hug init' first." >&2
+    return 1
+  fi
+
+  if [ "$force" = false ] && grep -q '"parentId"' .clasp.json 2>/dev/null; then
+    local parent_id
+    parent_id=$(grep '"parentId"' .clasp.json | sed 's/.*"parentId"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+    echo "Error: this is a container-bound script. Forking will create a standalone" >&2
+    echo "project, but the code may depend on its container (e.g. by calling." >&2
+    echo "getActiveSpreadsheet())." >&2
+    echo "" >&2
+    echo "Container: https://drive.google.com/file/d/$parent_id" >&2
+    echo "" >&2
+    echo "Use 'hug fork --force' to fork anyway." >&2
+    return 1
+  fi
+
+  local clasp
+  clasp=$(find_clasp)
+
+  local title
+  title="$(basename "$(pwd)")"
+
+  echo "Creating new Apps Script project '$title'..."
+  rm -f .clasp.json
+  run_clasp "$clasp" create --type standalone --title "$title"
+
+  echo "Pushing code to new project..."
+  run_clasp "$clasp" push
+
+  echo ""
+  echo "Fork complete. This directory now points to a new Apps Script project."
+}
+
+# ─── deploy ──────────────────────────────────────────────────────────────────
+
+cmd_deploy() {
+  if [ $# -gt 0 ] && [ "$1" = "--help" ]; then
+    echo "Usage: hug deploy [description]"
+    echo "       hug deploy --rollback <version>"
+    echo ""
+    echo "Pushes code, creates a version, and updates the deployment."
+    echo "If no deployment exists, creates one."
+    return 0
+  fi
+
+  local clasp
+  clasp=$(find_clasp)
+
+  # Rollback mode
+  if [ "${1:-}" = "--rollback" ]; then
+    if [ $# -ne 2 ]; then
+      echo "Usage: hug deploy --rollback <version>" >&2
+      return 1
+    fi
+    local version="$2"
+    local line
+    line=$(select_deployment "$clasp")
+    if [ -z "$line" ]; then
+      echo "Error: no non-HEAD deployment found to roll back" >&2
+      return 1
+    fi
+    local id desc
+    id=$(deployment_id "$line")
+    desc=$(deployment_desc "$line")
+    echo "Rolling back to version $version (deployment $id)..."
+    update_deployment "$clasp" "$id" "$version" "$desc"
+    echo "Done."
+    return 0
+  fi
+
+  local description="${*:-}"
+
+  echo "Pushing..."
+  run_clasp "$clasp" push
+
+  echo "Creating version..."
+  local version_output
+  version_output=$(run_clasp "$clasp" create-version "$description")
+  echo "$version_output"
+  local version
+  version=$(echo "$version_output" | grep -oE 'version [0-9]+' | grep -oE '[0-9]+')
+
+  if [ -z "$version" ]; then
+    echo "Error: could not parse version number from: $version_output" >&2
+    return 1
+  fi
+
+  local line
+  line=$(select_deployment "$clasp") || true
+
+  if [ -z "$line" ]; then
+    echo "No existing deployment found. Creating one..."
+    run_clasp "$clasp" create-deployment -V "$version" -d "$description"
+  else
+    local id desc
+    id=$(deployment_id "$line")
+    desc=$(deployment_desc "$line")
+    echo "Updating deployment $id to version $version..."
+    update_deployment "$clasp" "$id" "$version" "$desc"
+  fi
+
+  echo "Done."
+}
+
+# ─── config ──────────────────────────────────────────────────────────────────
+
+# Read config.js and output associative key-value lines: KEY=VALUE
+_read_config() {
+  if [ ! -f config.js ]; then
+    return 1
+  fi
+  grep -E "^  [A-Za-z_][A-Za-z0-9_]*:" config.js | sed "s/^  \([A-Za-z_][A-Za-z0-9_]*\): *['\"]\\(.*\\)['\"],\$/\\1=\\2/"
+}
+
+# Write config.js from KEY=VALUE lines on stdin
+_write_config() {
+  local entries=""
+  while IFS='=' read -r key value; do
+    entries="${entries}  ${key}: '${value}',
+"
+  done
+
+  if [ -z "$entries" ]; then
+    rm -f config.js
+    return
+  fi
+
+  cat > config.js <<EOF
+const CONFIG = {
+${entries}};
+EOF
+}
+
+cmd_config() {
+  if [ "${1:-}" = "--help" ]; then
+    echo "Usage: hug config"
+    echo "       hug config set KEY=VALUE ..."
+    echo "       hug config unset KEY ..."
+    echo ""
+    echo "Manages config.js, a JS constants file pushed with your code."
+    echo "Apps Script code can read values via CONFIG.KEY."
+    echo ""
+    echo "Note: config values are stored in source. Don't put secrets here."
+    return 0
+  fi
+
+  local subcmd="${1:-}"
+
+  case "$subcmd" in
+    "")
+      # List config
+      if [ ! -f config.js ]; then
+        echo "No config.js found. Use 'hug config set KEY=VALUE' to create one."
+        return 0
+      fi
+      _read_config | while IFS='=' read -r key value; do
+        echo "$key=$value"
+      done
+      ;;
+
+    set)
+      shift
+      if [ $# -eq 0 ]; then
+        echo "Usage: hug config set KEY=VALUE ..." >&2
+        return 1
+      fi
+
+      # Load existing config
+      local existing=""
+      if [ -f config.js ]; then
+        existing=$(_read_config)
+      fi
+
+      # Parse new values and merge
+      local new_pairs=""
+      for arg in "$@"; do
+        if ! echo "$arg" | grep -qE '^[A-Za-z_][A-Za-z0-9_]*='; then
+          echo "Error: invalid format '$arg'. Use KEY=VALUE." >&2
+          return 1
+        fi
+        local key="${arg%%=*}"
+        local value="${arg#*=}"
+        # Remove existing entry for this key if present
+        existing=$(echo "$existing" | grep -v "^${key}=" || true)
+        new_pairs="${new_pairs}${key}=${value}
+"
+      done
+
+      # Combine and write
+      { printf '%s\n%s' "$existing" "$new_pairs" | grep -v '^$' || true; } | _write_config
+      echo "Updated config.js."
+      ;;
+
+    unset)
+      shift
+      if [ $# -eq 0 ]; then
+        echo "Usage: hug config unset KEY ..." >&2
+        return 1
+      fi
+
+      if [ ! -f config.js ]; then
+        echo "No config.js found." >&2
+        return 1
+      fi
+
+      local remaining
+      remaining=$(_read_config)
+      for key in "$@"; do
+        remaining=$(echo "$remaining" | grep -v "^${key}=" || true)
+      done
+
+      { echo "$remaining" | grep -v '^$' || true; } | _write_config
+
+      if [ ! -f config.js ]; then
+        echo "Removed config.js (no keys remaining)."
+      else
+        echo "Updated config.js."
+      fi
+      ;;
+
+    *)
+      echo "Error: unknown config subcommand '$subcmd'" >&2
+      echo "Run 'hug config --help' for usage." >&2
+      return 1
+      ;;
+  esac
+}
+
+# ─── passthrough commands ────────────────────────────────────────────────────
+
+cmd_push() {
+  local clasp; clasp=$(find_clasp)
+  run_clasp "$clasp" push "$@"
+}
+
+cmd_pull() {
+  local force=false
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      -f|--force) force=true; shift ;;
+      --help)
+        echo "Usage: hug pull [-f|--force]"
+        echo ""
+        echo "Pulls remote files from Apps Script, overwriting local files."
+        echo "Refuses to run if there are uncommitted changes (use -f to override)."
+        return 0 ;;
+      *) break ;;
+    esac
+  done
+
+  if [ "$force" = false ] && ! git diff --quiet 2>/dev/null; then
+    echo "Error: you have uncommitted changes. Commit or stash them first," >&2
+    echo "or use 'hug pull --force' to overwrite." >&2
+    return 1
+  fi
+
+  local clasp; clasp=$(find_clasp)
+  run_clasp "$clasp" pull "$@"
+}
+
+cmd_open() {
+  local clasp; clasp=$(find_clasp)
+  run_clasp "$clasp" open "$@"
+}
+
+cmd_versions() {
+  local clasp; clasp=$(find_clasp)
+  run_clasp "$clasp" list-versions "$@"
+}
+
+cmd_deployments() {
+  local clasp; clasp=$(find_clasp)
+  run_clasp "$clasp" list-deployments "$@"
+}
+
+# ─── dispatch ────────────────────────────────────────────────────────────────
+
+if [ $# -eq 0 ]; then
+  usage
+  exit 1
+fi
+
+command="$1"
+shift
+
+case "$command" in
+  init)        cmd_init "$@" ;;
+  fork)        cmd_fork "$@" ;;
+  config)      cmd_config "$@" ;;
+  deploy)      cmd_deploy "$@" ;;
+  push)        cmd_push "$@" ;;
+  pull)        cmd_pull "$@" ;;
+  open)        cmd_open "$@" ;;
+  versions)    cmd_versions "$@" ;;
+  deployments) cmd_deployments "$@" ;;
+  --version|-v) echo "hug $VERSION" ;;
+  --help|-h)   usage ;;
+  *)
+    echo "Error: unknown command '$command'" >&2
+    echo "Run 'hug --help' for usage." >&2
+    exit 1
+    ;;
+esac

package/lib/common.sh

@@ -0,0 +1,108 @@
+# common.sh — shared functions for hug CLI
+
+# Ensure package.json exists and clasp is installed locally
+ensure_clasp() {
+  if [ ! -f package.json ]; then
+    echo "Initializing npm project..."
+    npm init -y --quiet >/dev/null
+  fi
+  if [ ! -d node_modules/.bin ] || [ ! -x node_modules/.bin/clasp ]; then
+    echo "Installing clasp..."
+    npm install --save-dev @google/clasp --quiet >/dev/null
+  fi
+}
+
+# Resolve the path to clasp, preferring local install
+find_clasp() {
+  if [ -x "./node_modules/.bin/clasp" ]; then
+    echo "./node_modules/.bin/clasp"
+  elif command -v clasp &>/dev/null; then
+    echo "clasp"
+  else
+    echo "Error: clasp not found. Run 'npm install @google/clasp' first." >&2
+    return 1
+  fi
+}
+
+# Run clasp and check for auth errors on failure
+run_clasp() {
+  local clasp="$1"
+  shift
+
+  local output
+  output=$("$clasp" "$@" 2>&1) && { echo "$output"; return 0; }
+  local exit_code=$?
+
+  echo "$output" >&2
+
+  if echo "$output" | grep -qiE "authorize|unauthorized|unauthenticated|login|credential|ENOENT.*clasprc|401"; then
+    echo "" >&2
+    echo "Hint: you may need to log in. Run 'npx clasp login' to authenticate." >&2
+  fi
+
+  return $exit_code
+}
+
+# Resolve the hug package root (where templates/ lives)
+hug_root() {
+  local source="${BASH_SOURCE[0]}"
+  while [ -L "$source" ]; do
+    local dir
+    dir="$(cd -P "$(dirname "$source")" && pwd)"
+    source="$(readlink "$source")"
+    [[ "$source" != /* ]] && source="$dir/$source"
+  done
+  cd -P "$(dirname "$source")/.." && pwd
+}
+
+# Get all non-HEAD deployment lines, select one interactively if multiple
+select_deployment() {
+  local clasp="$1"
+
+  local lines
+  lines=$(run_clasp "$clasp" list-deployments | grep '^-' | grep -v '@HEAD')
+
+  if [ -z "$lines" ]; then
+    echo ""
+    return
+  fi
+
+  local count
+  count=$(echo "$lines" | wc -l | tr -d ' ')
+
+  if [ "$count" -eq 1 ]; then
+    echo "$lines"
+  else
+    echo "Multiple deployments found. Choose one:" >&2
+    echo "$lines" | nl -w1 -s') ' >&2
+    printf "Choice: " >&2
+    read -r choice
+    local selected
+    selected=$(echo "$lines" | sed -n "${choice}p")
+    if [ -z "$selected" ]; then
+      echo "Error: invalid choice" >&2
+      return 1
+    fi
+    echo "$selected"
+  fi
+}
+
+# Extract deployment ID from a deployment line
+deployment_id() {
+  echo "$1" | awk '{print $2}'
+}
+
+# Extract description from a deployment line (may be empty)
+deployment_desc() {
+  echo "$1" | sed -n 's/^- [^ ]* @[^ ]* - \(.*\)/\1/p'
+}
+
+# Update a deployment, preserving its description if it has one
+update_deployment() {
+  local clasp="$1" id="$2" version="$3" desc="$4"
+  if [ -n "$desc" ]; then
+    run_clasp "$clasp" update-deployment "$id" -V "$version" -d "$desc"
+  else
+    run_clasp "$clasp" update-deployment "$id" -V "$version"
+  fi
+}

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@peterseibel/hug",
+  "version": "0.1.0",
+  "description": "A lightweight wrapper around clasp for managing Google Apps Script projects",
+  "bin": {
+    "hug": "bin/hug"
+  },
+  "keywords": ["google-apps-script", "clasp", "gas"],
+  "license": "ISC",
+  "dependencies": {
+    "@google/clasp": "^3.2.0"
+  }
+}

package/plans/hug-cli-tool.md

@@ -0,0 +1,132 @@
+# Plan: Transform this repo into `hug` — a general-purpose clasp wrapper
+
+## Context
+
+This repo currently contains a specific Apps Script app (BHS LC lottery form). We're turning it into `hug`, a lightweight CLI tool that wraps `clasp` to provide opinionated project management for Google Apps Script projects. The app-specific code will be removed; the deployment workflow in the `hug` script becomes the foundation.
+
+## Phase 1: Clean up — remove app-specific files
+
+**Delete:**
+- `Code.js` — app business logic
+- `index.html` — app UI
+- `appsscript.json` — app-specific manifest
+- `dev.clasp.json`, `prod.clasp.json` — app-specific project configs
+- `.clasp.json` — app-specific (will be recreated per-project by hug)
+- `plans/multi-project-deployment.md` — app-specific plan (concepts will be incorporated into hug's design)
+
+**Keep:**
+- `hug` script (will be rewritten)
+- `package.json` (will be rewritten)
+- `CLAUDE.md`, `README.md` (will be rewritten)
+- `.gitignore`
+- `.claude/` directory
+
+## Phase 2: Project structure
+
+```
+hug/
+├── bin/
+│   └── hug              # CLI entry point (bash)
+├── templates/
+│   ├── blank/
+│   │   ├── appsscript.json
+│   │   └── Code.js      # empty/minimal
+│   └── webapp/
+│       ├── appsscript.json   # with webapp config
+│       ├── Code.js           # doGet() stub
+│       └── index.html        # minimal HTML page
+├── lib/
+│   └── common.sh        # shared bash functions (clasp path resolution, error handling, deployment helpers)
+├── package.json          # bin field points to bin/hug, clasp as dependency
+├── .gitignore
+├── CLAUDE.md
+└── README.md
+```
+
+## Phase 3: CLI commands
+
+The `hug` script becomes a subcommand-based CLI. All commands assume clasp is available (bundled as a dependency).
+
+### `hug init [--template blank|webapp] [name]`
+- Creates a new Apps Script project directory (or uses current dir)
+- Copies template files into it
+- Runs `npm init -y` and `npm install @google/clasp`
+- Runs `clasp create --type standalone --title <name>` (or `--type webapp` for webapp template)
+- Result: a ready-to-push project
+
+### `hug import`
+- For adopting an existing Apps Script project
+- Runs `clasp clone <scriptId>` into current directory
+- Sets up the standard project structure (package.json with clasp dep, .gitignore)
+
+### `hug clone <scriptId> [directory]`
+- Creates a new Apps Script project, then pushes existing code to it
+- Basically: `clasp create` + copy files + `clasp push`
+- Useful for forking an existing project into a new script
+
+### `hug deploy [description]`
+- The current push→version→update-deployment workflow (what `hug` does now)
+- If no deployment exists yet, creates one
+- Preserves existing deployment descriptions
+
+### `hug deploy --rollback <version>`
+- Roll back a deployment to a previous version (existing functionality)
+
+### `hug push`
+- Thin wrapper: just runs `clasp push`
+- Convenience so you don't need to remember the clasp path
+
+### `hug pull`
+- Thin wrapper: just runs `clasp pull`
+
+### `hug open`
+- Thin wrapper: runs `clasp open`
+
+### `hug versions`
+- Lists versions (`clasp list-versions`)
+
+### `hug deployments`
+- Lists deployments (`clasp list-deployments`)
+
+## Phase 4: Rewrite `bin/hug`
+
+- Move current `hug` script to `bin/hug`
+- Refactor into subcommand dispatch (case statement)
+- Extract shared logic (clasp path resolution, deployment selection) into `lib/common.sh`
+- Add `--help` for each subcommand
+- The existing deploy logic stays largely intact, just reorganized
+
+## Phase 5: Templates
+
+### `templates/blank/`
+- `appsscript.json`: minimal manifest (V8 runtime, America/Los_Angeles timezone)
+- `Code.js`: empty file with a comment
+
+### `templates/webapp/`
+- `appsscript.json`: manifest with `webapp` section (executeAs USER_DEPLOYING, access ANYONE or DOMAIN)
+- `Code.js`: `doGet()` that serves `index.html`
+- `index.html`: minimal HTML5 boilerplate
+
+## Phase 6: Update package.json
+
+```json
+{
+  "name": "hug-clasp",
+  "version": "0.1.0",
+  "description": "A lightweight wrapper around clasp for managing Google Apps Script projects",
+  "bin": { "hug": "bin/hug" },
+  "dependencies": { "@google/clasp": "^3.2.0" }
+}
+```
+
+## Phase 7: Rewrite docs
+
+- `README.md`: document all commands with examples, installation instructions
+- `CLAUDE.md`: update to reflect new project structure and purpose
+
+## Verification
+
+1. Run `./bin/hug --help` — should show available commands
+2. Run `./bin/hug init --template webapp test-project` in a temp dir — should scaffold a project
+3. Run `./bin/hug deploy "test"` in an existing clasp project — should do push→version→deploy
+4. Run `./bin/hug versions` and `./bin/hug deployments` — should proxy to clasp

package/plans/hug-config.md

@@ -0,0 +1,83 @@
+# Plan: Add `hug config` for managing project configuration
+
+## Context
+
+After forking a project with `hug fork`, you need to configure it to point at
+different resources (e.g. a different spreadsheet). Using `clasp run` with
+script properties would be the "right" approach but requires heavy GCP setup
+(link project, enable API, create OAuth client, re-login with creds).
+
+Instead, use a simple local `config.js` file that gets pushed with the code.
+`hug config` manages this file, and Apps Script code reads from the `CONFIG`
+object directly. Each git branch can have different config values, which pairs
+well with `hug fork`.
+
+Config values end up in source/git, which is fine for things like spreadsheet
+IDs but means sensitive values shouldn't go here.
+
+## Files to modify
+
+- `bin/hug` — add `cmd_config` and dispatch entry
+- `README.md` — document the config command
+- `CLAUDE.md` — update command list and design decisions
+
+Templates are not modified — `config.js` is created on demand by `hug config set`.
+
+## Changes
+
+### 1. Add `cmd_config` to `bin/hug`
+
+```
+hug config                     # list all config values
+hug config set KEY=VALUE ...   # set one or more values
+hug config unset KEY ...       # remove one or more values
+```
+
+Implementation:
+
+**`hug config`** (no args): read `config.js`, parse and display key-value pairs.
+If no `config.js` exists, say "No config.js found."
+
+**`hug config set K=V ...`**: parse KEY=VALUE args. If `config.js` exists, read
+it and merge new values. If not, create it. Write the file as:
+
+```javascript
+const CONFIG = {
+  SPREADSHEET_ID: '1BxiM...',
+  SHEET_NAME: 'Data',
+};
+```
+
+**`hug config unset K ...`**: read `config.js`, remove specified keys, rewrite.
+If no keys remain, delete the file.
+
+The parser for reading `config.js` can be simple — grep for lines matching
+`KEY: 'VALUE'` or `KEY: "VALUE"` patterns. No need for a full JS parser since
+hug controls the file format.
+
+### 2. Add dispatch entry
+
+Add `config` to the case statement and usage block:
+
+```
+Configuration:
+  config                        List config values
+  config set KEY=VALUE ...      Set config values (writes config.js)
+  config unset KEY ...          Remove config values
+```
+
+### 3. Update docs
+
+- README: add config section with example workflow (init, config set, push)
+- CLAUDE.md: add config to command list and design decisions
+
+## Verification
+
+- `hug config --help` shows usage
+- `hug config` with no config.js prints "No config.js found."
+- `hug config set FOO=bar BAZ=qux` creates config.js with both values
+- `hug config` lists FOO and BAZ
+- `hug config set FOO=updated` changes FOO, keeps BAZ
+- `hug config unset FOO` removes FOO, keeps BAZ
+- `hug config unset BAZ` removes last key and deletes config.js
+- config.js is valid JavaScript that can be pushed to Apps Script

package/plans/multi-project-deployment.md

@@ -0,0 +1,78 @@
+# Multi-Project Deployment Plan
+
+## Goal
+
+Run the same codebase against different spreadsheets — e.g. a dev/staging instance and a production instance — without hardcoding any spreadsheet IDs in the code.
+
+## Background: Container-Bound vs. Standalone Scripts
+
+The current script is **container-bound**: it was created via Extensions > Apps Script from within a spreadsheet, so `SpreadsheetApp.getActiveSpreadsheet()` works automatically. This binding is stored in the spreadsheet, not the script, and there's no official way to convert a container-bound project to standalone.
+
+To share code across multiple independent spreadsheets, the script needs to be **standalone**, using `SpreadsheetApp.openById(id)` instead of `getActiveSpreadsheet()`.
+
+## Approach: Script Properties for Per-Project Config
+
+Script Properties (`PropertiesService.getScriptProperties()`) are stored per script project, not per deployment. This means each standalone script project gets its own independent property store — perfect for storing the spreadsheet ID.
+
+### Code changes
+
+Replace:
+```javascript
+SpreadsheetApp.getActiveSpreadsheet()
+```
+With:
+```javascript
+const id = PropertiesService.getScriptProperties().getProperty('SPREADSHEET_ID');
+SpreadsheetApp.openById(id);
+```
+
+Expose a `configure` function to set properties via `clasp run`:
+```javascript
+const configure = (config) => {
+  const props = PropertiesService.getScriptProperties();
+  Object.entries(config).forEach(([key, value]) => props.setProperty(key, value));
+};
+```
+
+## Workflow for Setting Up a New Project Instance
+
+1. **Create a new standalone script project:**
+   ```bash
+   clasp create --type standalone --title "Lottery Form - Dev"
+   ```
+   This updates `.clasp.json` with the new `scriptId`.
+
+2. **Push the code:**
+   ```bash
+   clasp push
+   ```
+
+3. **Configure the project** by running the `configure` function with a JSON config file:
+   ```bash
+   clasp run configure --params "$(< config.dev.json)"
+   ```
+   Where `config.dev.json` looks like:
+   ```json
+   [{"SPREADSHEET_ID": "1BxiM..."}]
+   ```
+   Note: `--params` always takes a JSON array; each element is one argument to the function.
+
+4. **Create a deployment:**
+   ```bash
+   clasp create-deployment -d "dev"
+   ```
+
+To switch a project to a different spreadsheet later, just re-run the `clasp run configure` step — no code changes or new version needed.
+
+## Managing Multiple Projects Locally
+
+Since `.clasp.json` only holds one `scriptId` at a time, keep separate config files for each project and swap them as needed:
+
+```
+.clasp.json.prod
+.clasp.json.dev
+config.prod.json
+config.dev.json
+```
+
+Or use separate git branches, one per project instance.

package/templates/blank/Code.js

@@ -0,0 +1,2 @@
+function myFunction() {
+}

package/templates/blank/appsscript.json

@@ -0,0 +1,5 @@
+{
+  "timeZone": "America/Los_Angeles",
+  "exceptionLogging": "STACKDRIVER",
+  "runtimeVersion": "V8"
+}

package/templates/webapp/Code.js

@@ -0,0 +1,4 @@
+function doGet() {
+  return HtmlService.createHtmlOutputFromFile('index')
+    .setTitle('My App');
+}

package/templates/webapp/appsscript.json

@@ -0,0 +1,9 @@
+{
+  "timeZone": "America/Los_Angeles",
+  "exceptionLogging": "STACKDRIVER",
+  "runtimeVersion": "V8",
+  "webapp": {
+    "executeAs": "USER_DEPLOYING",
+    "access": "ANYONE"
+  }
+}

package/templates/webapp/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <base target="_top">
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <style>
+    body { font-family: system-ui, sans-serif; max-width: 600px; margin: 2rem auto; padding: 0 1rem; }
+  </style>
+</head>
+<body>
+  <h1>Hello, world!</h1>
+</body>
+</html>