hub-launch 1.3.0 → 1.4.0

package/dist/services/git/FilePublishService.d.ts

@@ -0,0 +1,68 @@
+import type { Config } from '../../types/index.js';
+/**
+ * Options shared by publish/delete operations.
+ */
+export interface FilePublishOptions {
+    /** Commit message to use for the change. */
+    commitMessage?: string;
+    /** Target branch to publish to. Defaults to `config.uploadBranch ?? 'main'`. */
+    branch?: string;
+}
+/**
+ * FilePublishService — commit a single repo-relative file to a remote branch
+ * (default `origin/main`) using a temporary detached worktree, without ever
+ * touching the user's current branch or working tree.
+ *
+ * This encapsulates the worktree publish/delete dance that was previously
+ * inlined in `executeUpload`. Both plan upload and `/hula-execute` skill
+ * publishing share this one tested implementation.
+ *
+ * The flow for each operation is:
+ *   1. validate the target branch (injection guard)
+ *   2. resolve an absolute worktree base path
+ *   3. create a detached worktree off `origin/<branch>`
+ *   4. write (publish) or remove (delete) the file at `<worktree>/<relativePath>`
+ *   5. stage + commit (`git add .` stages deletions too) when there are changes
+ *   6. push `HEAD:<branch>`
+ *   7. always remove the worktree in `finally`
+ */
+export declare class FilePublishService {
+    private readonly config;
+    constructor(config: Config);
+    /**
+     * Default branch this service publishes to.
+     */
+    private defaultBranch;
+    /**
+     * Validate a branch value to prevent command injection in the git push
+     * refspec. Mirrors the guard in `executeUpload`.
+     */
+    private validateBranch;
+    /**
+     * Resolve the absolute worktree base path from config, identical to
+     * `executeUpload`'s behavior.
+     */
+    private resolveWorktreeBasePath;
+    /**
+     * Run `operation` inside a fresh detached worktree off `origin/<branch>`,
+     * commit (with `commitMessage`) if it produced changes, push to the branch,
+     * and always remove the worktree afterward.
+     */
+    private withWorktree;
+    /**
+     * Publish (create or update) a file on the target branch.
+     *
+     * @param relativePath - Repo-relative path of the file to write.
+     * @param content - The full content to write.
+     * @param opts - Optional commit message and branch override.
+     */
+    publishFile(relativePath: string, content: string, opts?: FilePublishOptions): Promise<void>;
+    /**
+     * Delete a file from the target branch.
+     *
+     * @param relativePath - Repo-relative path of the file to remove.
+     * @param opts - Optional commit message and branch override.
+     */
+    deleteFile(relativePath: string, opts?: FilePublishOptions): Promise<void>;
+}
+//# sourceMappingURL=FilePublishService.d.ts.map

package/dist/services/git/FilePublishService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilePublishService.d.ts","sourceRoot":"","sources":["../../../src/services/git/FilePublishService.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAKnD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,MAAM;IAI1B;;OAEG;IACH,OAAO,CAAC,aAAa;IAIrB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAiBtB;;;OAGG;YACW,uBAAuB;IAQrC;;;;OAIG;YACW,YAAY;IAuD1B;;;;;;OAMG;IACG,WAAW,CACf,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,IAAI,CAAC;IAWhB;;;;;OAKG;IACG,UAAU,CACd,YAAY,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,IAAI,CAAC;CAWjB"}

package/dist/services/git/FilePublishService.js

@@ -0,0 +1,141 @@
+import { dirname, isAbsolute, join, resolve } from 'path';
+import { mkdirSync, rmSync, writeFileSync } from 'fs';
+import { logger } from '../../utils/logger.js';
+import { WorktreeService } from './WorktreeService.js';
+import { getRepoInfo } from '../../utils/github-cli.js';
+import { getRepoRoot } from '../../utils/shell.js';
+/**
+ * FilePublishService — commit a single repo-relative file to a remote branch
+ * (default `origin/main`) using a temporary detached worktree, without ever
+ * touching the user's current branch or working tree.
+ *
+ * This encapsulates the worktree publish/delete dance that was previously
+ * inlined in `executeUpload`. Both plan upload and `/hula-execute` skill
+ * publishing share this one tested implementation.
+ *
+ * The flow for each operation is:
+ *   1. validate the target branch (injection guard)
+ *   2. resolve an absolute worktree base path
+ *   3. create a detached worktree off `origin/<branch>`
+ *   4. write (publish) or remove (delete) the file at `<worktree>/<relativePath>`
+ *   5. stage + commit (`git add .` stages deletions too) when there are changes
+ *   6. push `HEAD:<branch>`
+ *   7. always remove the worktree in `finally`
+ */
+export class FilePublishService {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Default branch this service publishes to.
+     */
+    defaultBranch() {
+        return this.config.uploadBranch ?? 'main';
+    }
+    /**
+     * Validate a branch value to prevent command injection in the git push
+     * refspec. Mirrors the guard in `executeUpload`.
+     */
+    validateBranch(branch) {
+        if (branch.includes(';') ||
+            branch.includes('|') ||
+            branch.includes('&') ||
+            branch.includes('$') ||
+            branch.includes('`') ||
+            branch.includes('\\') ||
+            branch.includes('\n') ||
+            branch.includes('\r') ||
+            branch.includes('\0') ||
+            branch.trim() === '') {
+            throw new Error(`Invalid branch value: "${branch}"`);
+        }
+    }
+    /**
+     * Resolve the absolute worktree base path from config, identical to
+     * `executeUpload`'s behavior.
+     */
+    async resolveWorktreeBasePath() {
+        const rawBasePath = this.config.worktreeBasePath ?? '.hula-worktrees';
+        const repoRoot = await getRepoRoot();
+        return isAbsolute(rawBasePath)
+            ? rawBasePath
+            : resolve(repoRoot, rawBasePath);
+    }
+    /**
+     * Run `operation` inside a fresh detached worktree off `origin/<branch>`,
+     * commit (with `commitMessage`) if it produced changes, push to the branch,
+     * and always remove the worktree afterward.
+     */
+    async withWorktree(type, branch, commitMessage, operation) {
+        this.validateBranch(branch);
+        const worktreeBasePath = await this.resolveWorktreeBasePath();
+        const repoInfo = await getRepoInfo();
+        const worktreeService = new WorktreeService({
+            basePath: worktreeBasePath,
+            repoName: repoInfo.name,
+        });
+        // Timestamp-based identifier to avoid collisions between concurrent publishes.
+        const identifier = `${Date.now()}`;
+        const worktreePath = worktreeService.getWorktreeDir(type, identifier);
+        let worktreeCreated = false;
+        try {
+            await worktreeService.createWorktreeAt(worktreePath, `origin/${branch}`, true);
+            worktreeCreated = true;
+            operation(worktreePath);
+            const hasChanges = await worktreeService.hasChangesAt(worktreePath);
+            if (hasChanges) {
+                await worktreeService.commitChangesAt(worktreePath, commitMessage);
+            }
+            else {
+                logger.info('No changes to commit, proceeding to push...');
+            }
+            // For a detached HEAD worktree we push HEAD directly to the target branch.
+            await worktreeService.pushAt(worktreePath, `HEAD:${branch}`);
+        }
+        finally {
+            if (worktreeCreated) {
+                try {
+                    await worktreeService.removeWorktreeAt(worktreePath);
+                }
+                catch (error) {
+                    logger.warning(`Failed to remove worktree at ${worktreePath}: ${error instanceof Error ? error.message : String(error)}`);
+                    logger.info(`You can manually remove it with: git worktree remove "${worktreePath}" --force`);
+                }
+            }
+        }
+    }
+    /**
+     * Publish (create or update) a file on the target branch.
+     *
+     * @param relativePath - Repo-relative path of the file to write.
+     * @param content - The full content to write.
+     * @param opts - Optional commit message and branch override.
+     */
+    async publishFile(relativePath, content, opts) {
+        const branch = opts?.branch ?? this.defaultBranch();
+        const commitMessage = opts?.commitMessage ?? 'chore: publish file via hula';
+        await this.withWorktree('publish', branch, commitMessage, (worktreePath) => {
+            const filePath = join(worktreePath, relativePath);
+            mkdirSync(dirname(filePath), { recursive: true });
+            writeFileSync(filePath, content, 'utf-8');
+        });
+    }
+    /**
+     * Delete a file from the target branch.
+     *
+     * @param relativePath - Repo-relative path of the file to remove.
+     * @param opts - Optional commit message and branch override.
+     */
+    async deleteFile(relativePath, opts) {
+        const branch = opts?.branch ?? this.defaultBranch();
+        const commitMessage = opts?.commitMessage ?? 'chore: remove file via hula';
+        await this.withWorktree('publish', branch, commitMessage, (worktreePath) => {
+            const filePath = join(worktreePath, relativePath);
+            // `commitChangesAt` runs `git add .`, which stages deletions, so a plain
+            // filesystem remove is sufficient here.
+            rmSync(filePath, { force: true });
+        });
+    }
+}
+//# sourceMappingURL=FilePublishService.js.map

package/dist/services/git/FilePublishService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilePublishService.js","sourceRoot":"","sources":["../../../src/services/git/FilePublishService.ts"],"names":[],"mappings":"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"}

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/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>`.