@therocketcode/gsd-core 1.4.0

package/scripts/setup-branch-protection.sh

@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+# setup-branch-protection.sh
+#
+# Apply branch protection rules to `main` and `next` for the GSD repo.
+# Idempotent — run as many times as you like. Re-running brings the live
+# rules back to what this script declares, so the script IS the source of
+# truth for branch protection.
+#
+# Usage:
+#   bash scripts/setup-branch-protection.sh             # apply both
+#   bash scripts/setup-branch-protection.sh main        # apply only main
+#   bash scripts/setup-branch-protection.sh next        # apply only next
+#   DRY_RUN=1 bash scripts/setup-branch-protection.sh   # show payloads, don't apply
+#
+# Requirements:
+#   - gh CLI authenticated against TheRocketCodeMX/gsd-core with admin scope
+#   - jq installed
+#
+# What it sets:
+#
+#   main (strict — production):
+#     - 2 required approving reviews
+#     - dismiss stale reviews on push
+#     - require code-owner review when CODEOWNERS applies
+#     - all required status checks must pass (defined in REQUIRED_CHECKS_MAIN below)
+#     - require branches to be up to date before merging  (ON — `main` is production)
+#     - require linear history (OFF — release back-merges use merge commits)
+#     - require conversation resolution
+#     - require signed commits
+#     - block force-push and deletion
+#     - admins included
+#
+#   next (loose — integration):
+#     - 1 required approving review
+#     - dismiss stale reviews on push
+#     - require code-owner review when CODEOWNERS applies
+#     - all required status checks must pass (defined in REQUIRED_CHECKS_NEXT below)
+#     - require branches to be up to date before merging  (OFF — this is the whole point)
+#     - require linear history (OFF — auto-backmerge from main needs merge commits
+#       to preserve the link from next's history to main's release tags;
+#       feature PRs still squash-merge by repo merge-strategy setting)
+#     - require conversation resolution
+#     - require signed commits (OFF on next — easier for contributors)
+#     - block force-push and deletion
+#     - admins included
+#
+# See: docs/adr/XXXX-introduce-next-integration-branch.md
+# See: docs/branching.md
+
+set -euo pipefail
+
+REPO="${REPO:-TheRocketCodeMX/gsd-core}"
+DRY_RUN="${DRY_RUN:-0}"
+
+# Required status checks. Adjust as your CI suite evolves.
+# The names must match the JOB NAME (not the workflow name) that GitHub
+# records — check existing PRs to confirm.
+REQUIRED_CHECKS_MAIN=(
+  "test"
+  "install-smoke"
+  "security-scan"
+  "Changeset Required / changeset-lint"
+  "Docs Required / docs-lint"
+  "PR Gate / size-check"
+  "Validate Branch Name / check-branch"
+)
+
+REQUIRED_CHECKS_NEXT=(
+  "test"
+  "PR Gate / size-check"
+  "Validate Branch Name / check-branch"
+  "Changeset Required / changeset-lint"
+  "Docs Required / docs-lint"
+  "PR Target Validator / validate-target"
+)
+
+require_cmd() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "ERROR: missing required command: $1" >&2
+    exit 1
+  }
+}
+
+require_cmd gh
+require_cmd jq
+
+verify_auth() {
+  if ! gh auth status >/dev/null 2>&1; then
+    echo "ERROR: gh CLI is not authenticated. Run 'gh auth login' first." >&2
+    exit 1
+  fi
+}
+
+build_payload() {
+  local branch="$1"
+  shift
+  local checks_array=("$@")
+
+  # Branch-specific knobs.
+  local approvals require_up_to_date linear_history signed_commits
+  case "$branch" in
+    main)
+      approvals=2
+      require_up_to_date=true
+      linear_history=false
+      signed_commits=true
+      ;;
+    next)
+      approvals=1
+      require_up_to_date=false
+      # linear_history=false: auto-backmerge from main needs merge commits to
+      # preserve the link to release tags. Feature PRs still produce one
+      # commit each via repo-level "squash and merge" default — that gives
+      # us a clean log without enforcing linearity at the protection layer.
+      linear_history=false
+      signed_commits=false
+      ;;
+    *)
+      echo "ERROR: unknown branch '$branch'" >&2
+      exit 1
+      ;;
+  esac
+
+  # Build the contexts array via jq for safe quoting.
+  local contexts_json
+  contexts_json=$(printf '%s\n' "${checks_array[@]}" | jq -R . | jq -s .)
+
+  jq -n \
+    --argjson contexts "$contexts_json" \
+    --argjson approvals "$approvals" \
+    --argjson require_up_to_date "$require_up_to_date" \
+    --argjson linear_history "$linear_history" \
+    --argjson signed_commits "$signed_commits" \
+    '{
+      required_status_checks: {
+        strict: $require_up_to_date,
+        contexts: $contexts
+      },
+      enforce_admins: true,
+      required_pull_request_reviews: {
+        dismiss_stale_reviews: true,
+        require_code_owner_reviews: true,
+        required_approving_review_count: $approvals,
+        require_last_push_approval: false
+      },
+      restrictions: null,
+      required_linear_history: $linear_history,
+      allow_force_pushes: false,
+      allow_deletions: false,
+      required_conversation_resolution: true,
+      required_signatures: $signed_commits,
+      lock_branch: false,
+      allow_fork_syncing: true
+    }'
+}
+
+apply_protection() {
+  local branch="$1"
+  local checks_var_name
+  if [ "$branch" = "main" ]; then
+    checks_var_name="REQUIRED_CHECKS_MAIN"
+  else
+    checks_var_name="REQUIRED_CHECKS_NEXT"
+  fi
+
+  # Expand the array indirectly (bash 3 compatible — macOS default).
+  eval "local checks=(\"\${${checks_var_name}[@]}\")"
+
+  local payload
+  payload=$(build_payload "$branch" "${checks[@]}")
+
+  echo "──────────────────────────────────────────"
+  echo "Branch: $branch"
+  echo "Required checks (${#checks[@]}):"
+  printf '  - %s\n' "${checks[@]}"
+  echo "──────────────────────────────────────────"
+
+  if [ "$DRY_RUN" = "1" ]; then
+    echo "[DRY RUN] Would PUT to /repos/${REPO}/branches/${branch}/protection:"
+    echo "$payload" | jq .
+    return 0
+  fi
+
+  echo "Applying branch protection..."
+  echo "$payload" | gh api \
+    -X PUT \
+    -H "Accept: application/vnd.github+json" \
+    -H "X-GitHub-Api-Version: 2022-11-28" \
+    --input - \
+    "/repos/${REPO}/branches/${branch}/protection" \
+    >/dev/null
+  echo "✓ Protection rules applied to $branch."
+}
+
+ensure_branch_exists() {
+  local branch="$1"
+  if ! gh api "/repos/${REPO}/branches/${branch}" >/dev/null 2>&1; then
+    echo "ERROR: branch '$branch' does not exist in $REPO." >&2
+    if [ "$branch" = "next" ]; then
+      cat <<EOF >&2
+
+Create the next branch first:
+  git checkout main && git pull --ff-only
+  git checkout -b next && git push -u origin next
+
+Then re-run this script.
+EOF
+    fi
+    exit 1
+  fi
+}
+
+main() {
+  verify_auth
+
+  local targets=()
+  if [ $# -eq 0 ]; then
+    targets=(main next)
+  else
+    targets=("$@")
+  fi
+
+  for branch in "${targets[@]}"; do
+    if [ "$branch" != "main" ] && [ "$branch" != "next" ]; then
+      echo "ERROR: unsupported branch '$branch'. Use 'main' or 'next'." >&2
+      exit 1
+    fi
+    ensure_branch_exists "$branch"
+    apply_protection "$branch"
+  done
+
+  echo ""
+  echo "Done. To verify: gh api /repos/${REPO}/branches/<branch>/protection | jq ."
+}
+
+main "$@"

package/scripts/strip-prose-atrefs.cjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * strip-prose-atrefs.cjs
+ *
+ * Removes redundant @~/.claude/gsd-core/ path tokens from prose lines
+ * in <process> and <context> blocks. The path is already declared in
+ * <execution_context> where it actually loads the file. Prose copies are
+ * inert and add ~900 tokens/invocation of dead weight.
+ *
+ * Transformation rules (applied per matching line):
+ *   - "Execute the X workflow from @PATH end-to-end." → "Execute end-to-end."
+ *   - "Execute @PATH end-to-end."                    → "Execute end-to-end."
+ *   - "Read and execute the X workflow from @PATH end-to-end." → "Execute end-to-end."
+ *   - "Follow the X workflow at @PATH."              → "Execute end-to-end."
+ *   - "Output the X reference from @PATH."           → "Execute end-to-end."
+ *   - "**Follow the X** from `@PATH`."               → "**Follow the X.**"
+ *   - "- If it is '...': ... from @PATH end-to-end." → strip path token only
+ *   - "- Otherwise: ... from @PATH end-to-end."      → strip path token only
+ *   - "- @PATH (label)"                              → "- (label)"
+ *
+ * Run with --dry-run to preview without writing.
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const DRY_RUN      = process.argv.includes('--dry-run');
+const ROOT         = path.join(__dirname, '..');
+const COMMANDS_DIR = path.join(ROOT, 'commands', 'gsd');
+
+const AT_PATH_PATTERN = /@(?:~|\$HOME)\/.+?gsd-core\/[^\s`)]+/;
+const mkAtRe = () => new RegExp(AT_PATH_PATTERN.source, 'g');
+
+function transformLine(line) {
+  if (!AT_PATH_PATTERN.test(line)) return line;
+
+  const trimmed = line.trim();
+
+  // "- @PATH (label)"  →  "- (label)"
+  if (/^- @(?:~|\$HOME)\//.test(trimmed)) {
+    return line.replace(/^(\s*- )@(?:~|\$HOME)\/[^\s(]+\s*/, '$1');
+  }
+
+  // "**Follow the X workflow** from `@PATH`."  →  "**Follow the X workflow.**"
+  // "**Follow the X workflow** from `@PATH`"   →  "**Follow the X workflow.**"
+  if (/\*\*Follow the .+ workflow\*\* from `@/.test(trimmed)) {
+    return line.replace(/\s+from `@(?:~|\$HOME)\/[^`]+`\.?/, '.');
+  }
+
+  // Routing bullet: keep everything except "from @PATH" or bare "@PATH"
+  // "- If …: … from @PATH end-to-end." → strip path, keep bullet
+  // "- Otherwise: … from @PATH end-to-end." → strip path, keep bullet
+  if (/^- (?:If |Otherwise:|pass all)/.test(trimmed)) {
+    return line
+      .replace(/\s+from\s+@(?:~|\$HOME)\/\S+/g, '')
+      .replace(/@(?:~|\$HOME)\/\S+/g, '');
+  }
+
+  // "Execute [the X workflow] [from] @PATH [end-to-end]."
+  // "Read and execute …"  /  "Follow …"  /  "Output …"
+  // → collapse to leading indent + "Execute end-to-end."
+  const indent = line.match(/^(\s*)/)[1];
+  return `${indent}Execute end-to-end.`;
+}
+
+function processFile(filePath) {
+  const original = fs.readFileSync(filePath, 'utf-8');
+  const lines    = original.split('\n');
+  const out      = [];
+  let inProse    = false; // true when inside <process> or <context> (not execution_context)
+
+  for (const line of lines) {
+    const t = line.trim();
+    if (/<(process|context)>/.test(t) && !t.includes('execution_context')) inProse = true;
+    if (/<\/(process|context)>/.test(t) && !t.includes('execution_context')) inProse = false;
+
+    if (inProse && AT_PATH_PATTERN.test(line)) {
+      const re = mkAtRe();
+      re.lastIndex = 0;
+      out.push(transformLine(line));
+    } else {
+      out.push(line);
+    }
+  }
+
+  const result = out.join('\n');
+  if (result === original) return false; // no change
+
+  if (!DRY_RUN) fs.writeFileSync(filePath, result, 'utf-8');
+  return true;
+}
+
+const files = fs.readdirSync(COMMANDS_DIR)
+  .filter(f => f.endsWith('.md'))
+  .map(f => path.join(COMMANDS_DIR, f));
+
+let changed = 0;
+for (const f of files) {
+  if (processFile(f)) {
+    console.log(`${DRY_RUN ? '[dry]' : 'fixed'}: ${path.basename(f)}`);
+    changed++;
+  }
+}
+console.log(`\n${changed} file(s) ${DRY_RUN ? 'would be' : 'were'} modified.`);

package/scripts/sync-manifest-versions.cjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * sync-manifest-versions.cjs
+ *
+ * Stamps the package.json version into every runtime-integration manifest whose
+ * top-level `version` field MUST track the package version.  Called automatically
+ * by the `version` npm lifecycle script so that `npm version X.Y.Z` keeps all
+ * registered manifests in sync.
+ *
+ * Usage:
+ *   node scripts/sync-manifest-versions.cjs           # stamp + report
+ *   node scripts/sync-manifest-versions.cjs --stage   # stamp + git-stage manifests
+ *   node scripts/sync-manifest-versions.cjs --check   # report drift, exit 1 if any
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+
+// Single source of truth: runtime-integration manifests whose top-level `version`
+// MUST track package.json. Add a new manifest here so `npm version` keeps it in
+// sync — the regression guard test (issue 844) fails if you forget.
+const VERSIONED_MANIFESTS = [
+  '.claude-plugin/plugin.json',
+  'gemini-extension.json',
+];
+
+function readJson(p) {
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function getPackageVersion(root) {
+  const r = root || ROOT;
+  return readJson(path.join(r, 'package.json')).version;
+}
+
+// Stamp `version` into each registered manifest, preserving field order and
+// 2-space + trailing-newline formatting. Returns the list of changed rel paths.
+function syncManifestVersions(opts) {
+  const root = (opts && opts.root) || ROOT;
+  const v = (opts && opts.version) != null ? opts.version : getPackageVersion(root);
+  const changed = [];
+  for (const rel of VERSIONED_MANIFESTS) {
+    const abs = path.join(root, rel);
+    const manifest = readJson(abs);
+    if (manifest.version !== v) {
+      manifest.version = v;
+      fs.writeFileSync(abs, JSON.stringify(manifest, null, 2) + '\n');
+      changed.push(rel);
+    }
+  }
+  return changed;
+}
+
+// Registered manifests whose version != package version.
+function findDrift(opts) {
+  const root = (opts && opts.root) || ROOT;
+  const v = (opts && opts.version) != null ? opts.version : getPackageVersion(root);
+  const drift = [];
+  for (const rel of VERSIONED_MANIFESTS) {
+    const found = readJson(path.join(root, rel)).version;
+    if (found !== v) drift.push({ manifest: rel, found, expected: v });
+  }
+  return drift;
+}
+
+// Best-effort outside git; fail-closed inside a work tree so a release never
+// ships a stale manifest that the working-tree test already accepted.
+function stageManifests(opts) {
+  const root = (opts && opts.root) || ROOT;
+  let insideWorkTree = false;
+  try {
+    insideWorkTree = execFileSync('git', ['rev-parse', '--is-inside-work-tree'], {
+      cwd: root,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString().trim() === 'true';
+  } catch {}
+  if (!insideWorkTree) {
+    console.warn('sync-manifest-versions: not a git work tree; skipping staging.');
+    return;
+  }
+  try {
+    execFileSync('git', ['add', '--', ...VERSIONED_MANIFESTS], { cwd: root, stdio: ['ignore', 'ignore', 'pipe'] });
+  } catch (err) {
+    const detail = err && err.stderr ? err.stderr.toString().trim() : (err && err.message) || 'unknown error';
+    throw new Error(`sync-manifest-versions: failed to git-add manifests inside a work tree: ${detail}`);
+  }
+}
+
+module.exports = { VERSIONED_MANIFESTS, syncManifestVersions, findDrift, getPackageVersion, stageManifests };
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const version = getPackageVersion();
+  if (args.includes('--check')) {
+    const drift = findDrift({ version });
+    if (drift.length) {
+      for (const d of drift) {
+        console.error('Manifest ' + d.manifest + ' version ' + d.found + ' != package.json ' + d.expected);
+      }
+      console.error('Run `node scripts/sync-manifest-versions.cjs` to fix.');
+      process.exitCode = 1;
+    } else {
+      console.log('All ' + VERSIONED_MANIFESTS.length + ' versioned manifests in sync at ' + version + '.');
+    }
+  } else {
+    const changed = syncManifestVersions({ version });
+    if (changed.length) {
+      console.log('Stamped ' + version + ' into: ' + changed.join(', '));
+    } else {
+      console.log('Versioned manifests already at ' + version + '.');
+    }
+    if (args.includes('--stage')) stageManifests();
+  }
+}

package/scripts/sync-rulesets.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO="${REPO:-TheRocketCodeMX/gsd-core}"
+ENFORCEMENT="${ENFORCEMENT:-evaluate}"
+
+case "$ENFORCEMENT" in
+  disabled|evaluate|active) ;;
+  *)
+    echo "ERROR: ENFORCEMENT must be one of: disabled|evaluate|active" >&2
+    exit 1
+    ;;
+esac
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+RULESETS_DIR="$SCRIPT_DIR/../.github/rulesets"
+
+for ruleset_file in "$RULESETS_DIR"/*.json; do
+  name="$(jq -r '.name' "$ruleset_file")"
+
+  body="$(jq --arg enforcement "$ENFORCEMENT" '.enforcement = $enforcement' "$ruleset_file")"
+
+  existing_id="$(gh api "repos/$REPO/rulesets" --jq ".[] | select(.name==\"$name\") | .id" 2>/dev/null || true)"
+
+  if [ -n "$existing_id" ]; then
+    gh api --method PUT "repos/$REPO/rulesets/$existing_id" \
+      --input - <<< "$body" > /dev/null
+    echo "[update] $name -> enforcement=$ENFORCEMENT"
+  else
+    gh api --method POST "repos/$REPO/rulesets" \
+      --input - <<< "$body" > /dev/null
+    echo "[create] $name -> enforcement=$ENFORCEMENT"
+  fi
+done