hub-launch 1.2.3 → 1.4.0

package/dist/templates/scripts/hula-execute-manage.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# hula-execute-manage.sh — management surface for the /hula-execute skill
+# Usage (exactly one action per call):
+#   bash .github/scripts/hula-execute-manage.sh --list
+#   bash .github/scripts/hula-execute-manage.sh --list-schedules
+#   bash .github/scripts/hula-execute-manage.sh --show <runId>
+#   bash .github/scripts/hula-execute-manage.sh --run-now <scheduleId>
+#   bash .github/scripts/hula-execute-manage.sh --cancel-schedule <scheduleId>
+#   bash .github/scripts/hula-execute-manage.sh --publish-skill <repo-relative-path>
+#   bash .github/scripts/hula-execute-manage.sh --delete-skill <repo-relative-path>
+#
+# Each invocation maps to the corresponding `hula execute …` call, captures its
+# output, and emits a single structured JSON object to stdout; all other output
+# goes to stderr.
+#
+# JSON contract (stdout):
+#   read verbs    : {"status":"success","kind":"list|list-schedules|show","cliOutput":"…"}
+#   run-now       : {"status":"success","kind":"run-now","runId":"…","cliOutput":"…"}
+#   cancel        : {"status":"success","kind":"cancel-schedule","scheduleId":"…","cliOutput":"…"}
+#   publish-skill : {"status":"success","kind":"publish-skill","path":"…","cliOutput":"…"}
+#   delete-skill  : {"status":"success","kind":"delete-skill","path":"…","cliOutput":"…"}
+#   failure       : {"status":"error","code":<n>,"message":"…"}
+#
+# Exit codes: 0=success, 1=user error, 2=tool error
+#
+# Security: never prints secrets. Credentials are resolved inside the CLI from
+# flags/config/env — they are NOT passed by this script. --publish-skill and
+# --delete-skill reject path traversal and require a .hublaunch/skills/ path.
+
+set -euo pipefail
+
+# ── helpers ────────────────────────────────────────────────────────────────────
+
+json_escape() {
+  if command -v jq &>/dev/null; then
+    # jq -Rs . reads stdin as a raw string and outputs a JSON string (with surrounding quotes).
+    # Strip the surrounding quotes; the escaped content is safe to embed in JSON.
+    printf '%s' "$1" | jq -Rs . | sed 's/^"//;s/"$//'
+  else
+    # Fallback: escape backslashes and double quotes, collapse control chars to spaces
+    printf '%s' "$1" \
+      | sed 's/\\/\\\\/g; s/"/\\"/g' \
+      | tr '\n\r\t' '   '
+  fi
+}
+
+die() {
+  local code="$1"; shift
+  local safe_msg
+  safe_msg=$(json_escape "$*")
+  printf '{"status":"error","code":%d,"message":"%s"}\n' "$code" "$safe_msg" >&1
+  exit "$code"
+}
+
+# Validate a skill path: must be repo-relative, under .hublaunch/skills/, no traversal.
+validate_skill_path() {
+  local p="$1"
+  case "$p" in
+    /*) die 1 "Skill path must be repo-relative, not absolute: ${p}" ;;
+  esac
+  if printf '%s' "$p" | grep -q '\.\.'; then
+    die 1 "Invalid skill path (path traversal not allowed): ${p}"
+  fi
+  case "$p" in
+    .hublaunch/skills/*) : ;;
+    *) die 1 "Skill path must be under .hublaunch/skills/ — got ${p}" ;;
+  esac
+}
+
+# ── argument parsing ────────────────────────────────────────────────────────────
+# Exactly one action flag is allowed per call.
+
+ACTION=''
+ARG=''
+
+set_action() {
+  if [[ -n "$ACTION" ]]; then
+    die 1 "Provide exactly one action (got --$ACTION and $1)."
+  fi
+  ACTION="$1"
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --list)                   set_action 'list'; shift ;;
+    --list-schedules)         set_action 'list-schedules'; shift ;;
+    --show)                   set_action 'show'; ARG="$2"; shift 2 ;;
+    --show=*)                 set_action 'show'; ARG="${1#--show=}"; shift ;;
+    --run-now)                set_action 'run-now'; ARG="$2"; shift 2 ;;
+    --run-now=*)              set_action 'run-now'; ARG="${1#--run-now=}"; shift ;;
+    --cancel-schedule)        set_action 'cancel-schedule'; ARG="$2"; shift 2 ;;
+    --cancel-schedule=*)      set_action 'cancel-schedule'; ARG="${1#--cancel-schedule=}"; shift ;;
+    --publish-skill)          set_action 'publish-skill'; ARG="$2"; shift 2 ;;
+    --publish-skill=*)        set_action 'publish-skill'; ARG="${1#--publish-skill=}"; shift ;;
+    --delete-skill)           set_action 'delete-skill'; ARG="$2"; shift 2 ;;
+    --delete-skill=*)         set_action 'delete-skill'; ARG="${1#--delete-skill=}"; shift ;;
+    *)                        die 1 "Unexpected argument: $1" ;;
+  esac
+done
+
+if [[ -z "$ACTION" ]]; then
+  die 1 "Usage: bash .github/scripts/hula-execute-manage.sh (--list | --list-schedules | --show <id> | --run-now <id> | --cancel-schedule <id> | --publish-skill <path> | --delete-skill <path>)"
+fi
+
+# Actions that require an argument.
+case "$ACTION" in
+  show|run-now|cancel-schedule|publish-skill|delete-skill)
+    [[ -n "$ARG" ]] || die 1 "--$ACTION requires an argument." ;;
+esac
+
+# Path validation for skill file actions.
+case "$ACTION" in
+  publish-skill|delete-skill) validate_skill_path "$ARG" ;;
+esac
+
+# ── Build and run the hula execute invocation ────────────────────────────────
+
+CLI_ARGS=()
+case "$ACTION" in
+  list)            CLI_ARGS=(--list) ;;
+  list-schedules)  CLI_ARGS=(--list-schedules) ;;
+  show)            CLI_ARGS=(--show "$ARG") ;;
+  run-now)         CLI_ARGS=(--run-now "$ARG") ;;
+  cancel-schedule) CLI_ARGS=(--cancel-schedule "$ARG") ;;
+  publish-skill)   CLI_ARGS=(--publish-skill "$ARG") ;;
+  delete-skill)    CLI_ARGS=(--delete-skill "$ARG") ;;
+esac
+
+printf '⚙️  hula execute --%s...\n' "$ACTION" >&2
+
+OUTPUT=$(hula execute "${CLI_ARGS[@]}" 2>&1) || die 2 "Management action failed: $OUTPUT"
+
+SAFE_OUTPUT=$(json_escape "$OUTPUT")
+
+# ── Emit the structured JSON result ──────────────────────────────────────────
+
+case "$ACTION" in
+  list|list-schedules|show)
+    printf '{"status":"success","kind":"%s","cliOutput":"%s"}\n' \
+      "$ACTION" "$SAFE_OUTPUT"
+    ;;
+  run-now)
+    # The CLI prints "  ID:        <id>" for the new run.
+    RUN_ID=$(printf '%s' "$OUTPUT" | grep -E '^\s*ID:' | head -1 | sed -E 's/^\s*ID:\s*//') || true
+    SAFE_ID=$(json_escape "$RUN_ID")
+    printf '{"status":"success","kind":"run-now","runId":"%s","cliOutput":"%s"}\n' \
+      "$SAFE_ID" "$SAFE_OUTPUT"
+    ;;
+  cancel-schedule)
+    SAFE_ID=$(json_escape "$ARG")
+    printf '{"status":"success","kind":"cancel-schedule","scheduleId":"%s","cliOutput":"%s"}\n' \
+      "$SAFE_ID" "$SAFE_OUTPUT"
+    ;;
+  publish-skill|delete-skill)
+    SAFE_PATH=$(json_escape "$ARG")
+    printf '{"status":"success","kind":"%s","path":"%s","cliOutput":"%s"}\n' \
+      "$ACTION" "$SAFE_PATH" "$SAFE_OUTPUT"
+    ;;
+esac

package/dist/templates/scripts/hula-execute-run.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# hula-execute-run.sh — runs the hula.execute workflow for the /hula-execute skill
+# Usage:
+#   bash .github/scripts/hula-execute-run.sh \
+#     (--built-in <name> | --action-path <path>) \
+#     [--entry-point <path>] [--outcome-type <pr|plan|feedback>] [--schedule "<cron>"]
+#
+# Performs: hula execute (one-off run, or a recurring schedule when --schedule is given).
+# Outputs a single structured JSON object to stdout; all other output goes to stderr.
+#
+# JSON contract (stdout):
+#   one-off run : {"status":"success","kind":"run","runId":"…","prUrl":"…","cliOutput":"…"}
+#   schedule    : {"status":"success","kind":"schedule","scheduleId":"…","cronExpr":"…","cliOutput":"…"}
+#   failure     : {"status":"error","code":<n>,"message":"…"}
+#
+# Exit codes: 0=success, 1=user error, 2=tool error
+#
+# Security: never prints secrets. Credentials are resolved inside the CLI from
+# flags/config/env — they are NOT passed by this script.
+
+set -euo pipefail
+
+# ── helpers ────────────────────────────────────────────────────────────────────
+
+json_escape() {
+  if command -v jq &>/dev/null; then
+    # jq -Rs . reads stdin as a raw string and outputs a JSON string (with surrounding quotes).
+    # Strip the surrounding quotes; the escaped content is safe to embed in JSON.
+    printf '%s' "$1" | jq -Rs . | sed 's/^"//;s/"$//'
+  else
+    # Fallback: escape backslashes and double quotes, collapse control chars to spaces
+    printf '%s' "$1" \
+      | sed 's/\\/\\\\/g; s/"/\\"/g' \
+      | tr '\n\r\t' '   '
+  fi
+}
+
+die() {
+  local code="$1"; shift
+  local safe_msg
+  safe_msg=$(json_escape "$*")
+  printf '{"status":"error","code":%d,"message":"%s"}\n' "$code" "$safe_msg" >&1
+  exit "$code"
+}
+
+# ── argument parsing ────────────────────────────────────────────────────────────
+
+BUILT_IN=''
+ACTION_PATH=''
+ENTRY_POINT=''
+OUTCOME_TYPE=''
+SCHEDULE=''
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --built-in)        BUILT_IN="$2"; shift 2 ;;
+    --built-in=*)      BUILT_IN="${1#--built-in=}"; shift ;;
+    --action-path)     ACTION_PATH="$2"; shift 2 ;;
+    --action-path=*)   ACTION_PATH="${1#--action-path=}"; shift ;;
+    --entry-point)     ENTRY_POINT="$2"; shift 2 ;;
+    --entry-point=*)   ENTRY_POINT="${1#--entry-point=}"; shift ;;
+    --outcome-type)    OUTCOME_TYPE="$2"; shift 2 ;;
+    --outcome-type=*)  OUTCOME_TYPE="${1#--outcome-type=}"; shift ;;
+    --schedule)        SCHEDULE="$2"; shift 2 ;;
+    --schedule=*)      SCHEDULE="${1#--schedule=}"; shift ;;
+    *)                 die 1 "Unexpected argument: $1" ;;
+  esac
+done
+
+# Exactly one of --built-in / --action-path is required.
+if [[ -n "$BUILT_IN" && -n "$ACTION_PATH" ]]; then
+  die 1 "Provide either --built-in or --action-path, not both."
+fi
+if [[ -z "$BUILT_IN" && -z "$ACTION_PATH" ]]; then
+  die 1 "Usage: bash .github/scripts/hula-execute-run.sh (--built-in <name> | --action-path <path>) [--entry-point <path>] [--outcome-type <pr|plan|feedback>] [--schedule \"<cron>\"]"
+fi
+
+# Reject directory-traversal in --action-path, except for https:// URLs.
+if [[ -n "$ACTION_PATH" ]] && [[ "$ACTION_PATH" != https://* ]]; then
+  if printf '%s' "$ACTION_PATH" | grep -q '\.\.'; then
+    die 1 "Invalid action path (path traversal not allowed): ${ACTION_PATH}"
+  fi
+fi
+
+# ── Run hula execute ─────────────────────────────────────────────────────────
+
+ARGS=()
+if [[ -n "$BUILT_IN" ]]; then
+  ARGS+=(--built-in "$BUILT_IN")
+else
+  ARGS+=(--action-path "$ACTION_PATH")
+fi
+[[ -n "$ENTRY_POINT" ]]  && ARGS+=(--entry-point "$ENTRY_POINT")
+[[ -n "$OUTCOME_TYPE" ]] && ARGS+=(--outcome-type "$OUTCOME_TYPE")
+[[ -n "$SCHEDULE" ]]     && ARGS+=(--schedule "$SCHEDULE")
+
+if [[ -n "$SCHEDULE" ]]; then
+  printf '⏰ Scheduling execute-action (%s)...\n' "$SCHEDULE" >&2
+else
+  printf '🚀 Running execute-action...\n' >&2
+fi
+
+OUTPUT=$(hula execute "${ARGS[@]}" 2>&1) || die 2 "Execute failed: $OUTPUT"
+
+# ── Parse identifiers from the human-readable CLI output ─────────────────────
+# Parsing is intentionally tolerant: a missing identifier becomes an empty
+# string and we still report success, falling back to the raw cliOutput.
+
+# Distinguish a schedule from a one-off run by the CLI's success banner.
+if printf '%s' "$OUTPUT" | grep -q 'Schedule created successfully'; then
+  KIND='schedule'
+elif printf '%s' "$OUTPUT" | grep -q 'Execute action queued successfully'; then
+  KIND='run'
+elif [[ -n "$SCHEDULE" ]]; then
+  KIND='schedule'
+else
+  KIND='run'
+fi
+
+# The CLI prints "  ID:        <id>" for the run/schedule identifier.
+PARSED_ID=$(printf '%s' "$OUTPUT" | grep -E '^\s*ID:' | head -1 | sed -E 's/^\s*ID:\s*//') || true
+SAFE_OUTPUT=$(json_escape "$OUTPUT")
+
+if [[ "$KIND" == 'schedule' ]]; then
+  # "  Cron:    <expr>" — fall back to the schedule we sent if the label is absent.
+  CRON_EXPR=$(printf '%s' "$OUTPUT" | grep -E '^\s*Cron:' | head -1 | sed -E 's/^\s*Cron:\s*//') || true
+  [[ -z "$CRON_EXPR" ]] && CRON_EXPR="$SCHEDULE"
+  SAFE_ID=$(json_escape "$PARSED_ID")
+  SAFE_CRON=$(json_escape "$CRON_EXPR")
+  printf '{"status":"success","kind":"schedule","scheduleId":"%s","cronExpr":"%s","cliOutput":"%s"}\n' \
+    "$SAFE_ID" "$SAFE_CRON" "$SAFE_OUTPUT"
+else
+  # "  PR:        <url>"
+  PR_URL=$(printf '%s' "$OUTPUT" | grep -E '^\s*PR:' | head -1 | sed -E 's/^\s*PR:\s*//') || true
+  SAFE_ID=$(json_escape "$PARSED_ID")
+  SAFE_PR=$(json_escape "$PR_URL")
+  printf '{"status":"success","kind":"run","runId":"%s","prUrl":"%s","cliOutput":"%s"}\n' \
+    "$SAFE_ID" "$SAFE_PR" "$SAFE_OUTPUT"
+fi

package/dist/templates/skill-creation-instructions.md

@@ -0,0 +1,142 @@
+# Execute Skill Creation Instructions
+
+These instructions drive the **create-from-description** mode of the
+`/hula-execute` skill: turning a plain-language description into a published
+action file that `hula execute` can run or schedule.
+
+The action file is plain instruction markdown that the hula-project server reads
+from `origin/<uploadBranch>` (default `main`) at run time. It is **not** an Agent
+Skill and is never registered as a slash command — it lives under
+`.hublaunch/skills/`.
+
+Follow these steps in order. Do **not** skip the question step, and do **not**
+run `hula execute` before the file is successfully published.
+
+## Step 1: Ask clarifying questions first (then STOP)
+
+Mirror the `/hula-plan` question-first behavior. Before writing anything, ask the
+user the questions you cannot confidently answer from their description:
+
+1. **What should the action do?** The concrete task to perform on each run
+   (e.g. "remove unreachable code", "upgrade dependencies and fix breakages").
+2. **Target entry point** (optional): the file, directory, or URL the action
+   focuses on (e.g. `src/`). Maps to `--entry-point`.
+3. **Outcome type**: `pr` (open a pull request), `plan` (produce a plan), or
+   `feedback` (review/report only). Maps to `--outcome-type`. Default `pr`.
+4. **One-off or scheduled?** If recurring, get the schedule phrase (e.g. "every
+   night", "every Monday 9am").
+5. **Any constraints / scope limits** the run must respect (optional).
+
+**STOP and wait for the answers.** Do not proceed to authoring until the user
+responds. If anything is still ambiguous after the answers, ask a focused
+follow-up round.
+
+## Step 2: Confirm the action name
+
+Derive a default slug from the description: lowercase, hyphen-separated, no
+spaces or punctuation (e.g. "remove unreachable code in src" →
+`remove-unreachable-code`). Propose it to the user and let them override. Confirm
+the final name before writing the file.
+
+## Step 3: Resolve the schedule (if recurring)
+
+If the action is scheduled, translate the phrase to a 5-field cron expression
+using the preset table in `SKILL.md`, then **echo the cron with a plain-English
+readback and confirm it** before publishing/running. There is no server-side
+cron validation, so the readback + confirmation is mandatory.
+
+## Step 4: Compute the filename and path
+
+- Filename: `YYYY-MM-DD-HH:MM-<name-slug>.md`
+  - Use today's date and the current time on a 24-hour clock.
+  - `<name-slug>` is the confirmed, lowercase-hyphenated action name.
+- Repo-relative path: `.hublaunch/skills/<filename>`
+- Create the `.hublaunch/skills/` directory if it does not exist.
+
+## Step 5: Write the action file (free-form instruction markdown, NO frontmatter)
+
+Use the `Write` tool to create the file at the computed path. The content MUST be
+free-form instruction markdown with **no YAML frontmatter** (frontmatter would
+make it look like an Agent Skill). Follow this template:
+
+```markdown
+# <Action Title>
+
+## Goal
+<1–3 sentences describing what this action should accomplish.>
+
+## Steps
+1. <step>
+2. <step>
+3. <step>
+
+## Constraints
+- <optional: what must not change / scope limits>
+
+## Outcome
+<What the run should produce, consistent with the chosen --outcome-type:
+ pr | plan | feedback.>
+```
+
+Fill the template from the user's answers. Omit the `## Constraints` section if
+the user gave no constraints.
+
+## Step 6: Publish to origin/main BEFORE running (mandatory ordering)
+
+The server clones the repository and reads the action file from the default
+branch at run time (and re-reads it on every scheduled fire). The file MUST be on
+the branch before the run, so publish it first:
+
+```bash
+bash .github/scripts/hula-execute-manage.sh --publish-skill .hublaunch/skills/<filename>
+```
+
+Parse the single JSON object it prints:
+
+- If `status` is `"error"`: display `❌ <message>` and **STOP**. Do **not** run
+  `hula execute` — the file is not on the branch, so the run would fail.
+- If `status` is `"success"`: continue to Step 7.
+
+## Step 7: Run or schedule the action
+
+Only after a successful publish, invoke the run wrapper with `--action-path`
+pointing at the committed file:
+
+```bash
+bash .github/scripts/hula-execute-run.sh --action-path .hublaunch/skills/<filename> [--entry-point <path>] [--outcome-type <type>] [--schedule "<cron>"]
+```
+
+Pass only the flags you resolved. Quote the cron expression.
+
+## Step 8: Report the result
+
+Parse the run wrapper's JSON (same contract as the normal run flow) and report:
+
+- The **created file path** (`.hublaunch/skills/<filename>`) and that it was
+  published to `origin/<uploadBranch>`.
+- The **run or schedule result**:
+  - One-off run → the Run ID and PR link (if any), plus
+    `hula execute --show <runId>` to check status.
+  - Schedule → the Schedule ID and cron expression, plus a note that you can
+    manage it with `/hula-execute list`, `/hula-execute run now <id>`,
+    `/hula-execute cancel <id>`, or `/hula-execute update <id> …`.
+
+Example success report:
+
+```
+✅ Action created and published
+
+📄 **File**: .hublaunch/skills/2026-06-19-16:35-remove-unreachable-code.md (on origin/main)
+🔖 **Schedule ID**: sch_abc123
+⏰ **Cron**: 0 3 * * * (every day at 3:00 AM)
+
+Manage it with: /hula-execute list · /hula-execute run now sch_abc123 · /hula-execute cancel sch_abc123
+```
+
+## Notes
+
+- Never echo secrets. Credentials resolve inside the CLI.
+- The action file is committed to `origin/<uploadBranch>` via a temporary
+  worktree — the user's current branch and working tree are never touched.
+- If the publish succeeds but the run fails, the file remains on the branch; the
+  user can re-run it later with `/hula-execute .hublaunch/skills/<filename>`.