@vyuhlabs/dxkit 2.5.1 → 2.6.0

package/dist/setup-branch-protection.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * `vyuh-dxkit setup-branch-protection` — configures branch protection
+ * on the repo's default branch with dxkit's guardrail workflow listed
+ * as a required status check. Without this step, the dxkit-guardrails
+ * workflow we install only runs informationally — PRs can merge even
+ * if the guardrail fails. With it, merges are blocked on guardrail
+ * failures.
+ *
+ * Wraps `gh api -X PUT repos/{owner}/{repo}/branches/{branch}/protection`
+ * with a JSON payload that:
+ *   1. Adds `dxkit-guardrails` to required status checks
+ *   2. Preserves any other required checks already configured
+ *      (idempotent merge — don't clobber customer policy)
+ *   3. Doesn't force a review-count policy by default (set --require-reviews=N if wanted)
+ *
+ * Edge cases handled:
+ *   - gh CLI missing → preflight fails with clear install instructions
+ *   - No github.com remote → resolveOwnerRepo throws GhError with suggestion
+ *   - Customer not admin (HTTP 403) → ghApi throws with admin-asks suggestion
+ *   - Workflow file missing → warn before applying (the protection rule
+ *     would otherwise block ALL PRs until the workflow exists)
+ *   - Existing protection rule with different required checks → merge
+ *     dxkit-guardrails into the list instead of replacing
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSetupBranchProtection = runSetupBranchProtection;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const logger = __importStar(require("./logger"));
+const setup_gh_1 = require("./setup-gh");
+const REQUIRED_CHECK = 'dxkit-guardrails';
+function readExistingProtection(cwd, owner, repo, branch) {
+    try {
+        return (0, setup_gh_1.ghApi)(`repos/${owner}/${repo}/branches/${branch}/protection`, {
+            cwd,
+            method: 'GET',
+        });
+    }
+    catch (e) {
+        if (e instanceof setup_gh_1.GhError && e.httpStatus === 404) {
+            // No protection rule exists yet — that's expected for the
+            // common case where we're the first to configure one.
+            return null;
+        }
+        throw e;
+    }
+}
+/**
+ * Build the protection payload by merging dxkit-guardrails into any
+ * existing required-checks list. Preserves customer-configured
+ * required checks, review counts, and admin-enforcement settings.
+ */
+function buildPayload(existing, opts) {
+    // Existing required checks — preserve, then ensure dxkit-guardrails is in the set.
+    const existingChecks = existing?.required_status_checks?.contexts ?? [];
+    const mergedChecks = opts.force
+        ? [REQUIRED_CHECK]
+        : [...new Set([...existingChecks, REQUIRED_CHECK])];
+    // Reviews policy — only override when the customer passed --require-reviews.
+    // Without it, preserve whatever was there (or set null if no prior rule).
+    let reviews = null;
+    if (opts.requireReviews !== undefined && opts.requireReviews > 0) {
+        reviews = {
+            dismiss_stale_reviews: false,
+            require_code_owner_reviews: false,
+            required_approving_review_count: opts.requireReviews,
+        };
+    }
+    else if (existing?.required_pull_request_reviews) {
+        reviews = existing.required_pull_request_reviews;
+    }
+    return {
+        required_status_checks: { strict: false, contexts: mergedChecks },
+        enforce_admins: existing?.enforce_admins ?? false,
+        required_pull_request_reviews: reviews,
+        restrictions: null, // user/team push restrictions — out of scope here
+    };
+}
+function checkWorkflowFile(cwd) {
+    const wfPath = path.join(cwd, '.github', 'workflows', 'dxkit-guardrails.yml');
+    return fs.existsSync(wfPath);
+}
+async function runSetupBranchProtection(cwd, opts = {}) {
+    logger.header('vyuh-dxkit setup-branch-protection');
+    if (!(0, setup_gh_1.preflightGhCli)('setup-branch-protection')) {
+        process.exitCode = 1;
+        return;
+    }
+    let ownerRepo;
+    try {
+        ownerRepo = (0, setup_gh_1.resolveOwnerRepo)(cwd);
+    }
+    catch (e) {
+        if (e instanceof setup_gh_1.GhError) {
+            process.exitCode = (0, setup_gh_1.renderGhError)(e, 'Resolve repo');
+            return;
+        }
+        throw e;
+    }
+    const { owner, repo } = ownerRepo;
+    const branch = opts.branch ?? (0, setup_gh_1.resolveDefaultBranch)(cwd);
+    // Warn if the workflow file isn't present — protection-by-name would
+    // otherwise block ALL PRs until the workflow is added.
+    if (!checkWorkflowFile(cwd)) {
+        logger.warn('No .github/workflows/dxkit-guardrails.yml found. Applying branch protection ' +
+            'now would block every PR until that workflow exists.');
+        logger.dim('  → Run `vyuh-dxkit init --with-ci --yes` first to scaffold the workflow.');
+        process.exitCode = 1;
+        return;
+    }
+    logger.info(`Resolving existing protection on ${owner}/${repo}#${branch}...`);
+    let existing;
+    try {
+        existing = readExistingProtection(cwd, owner, repo, branch);
+    }
+    catch (e) {
+        if (e instanceof setup_gh_1.GhError) {
+            process.exitCode = (0, setup_gh_1.renderGhError)(e, 'Read existing protection');
+            return;
+        }
+        throw e;
+    }
+    if (existing) {
+        logger.info(`  → Found ${existing.required_status_checks?.contexts.length ?? 0} existing required check(s); ` +
+            `dxkit-guardrails ${existing.required_status_checks?.contexts.includes(REQUIRED_CHECK)
+                ? 'already in list'
+                : 'will be merged in'}.`);
+    }
+    else {
+        logger.info('  → No existing protection rule; creating one with dxkit-guardrails as required.');
+    }
+    const payload = buildPayload(existing, opts);
+    logger.info(`Applying protection: required checks = [${payload.required_status_checks?.contexts.join(', ')}]; ` +
+        `reviews required = ${payload.required_pull_request_reviews?.required_approving_review_count ?? 0}.`);
+    try {
+        (0, setup_gh_1.ghApi)(`repos/${owner}/${repo}/branches/${branch}/protection`, {
+            cwd,
+            method: 'PUT',
+            inputJson: JSON.stringify(payload),
+        });
+    }
+    catch (e) {
+        if (e instanceof setup_gh_1.GhError) {
+            process.exitCode = (0, setup_gh_1.renderGhError)(e, 'Apply protection');
+            return;
+        }
+        throw e;
+    }
+    console.log(''); // slop-ok
+    logger.success(`Branch protection applied to ${owner}/${repo}#${branch}.`);
+    logger.dim(`  → Verify: https://github.com/${owner}/${repo}/settings/branches`);
+    if (!payload.required_pull_request_reviews) {
+        logger.dim('  → Review-count policy NOT changed (pass --require-reviews=N to require reviews).');
+    }
+}
+//# sourceMappingURL=setup-branch-protection.js.map

package/dist/setup-branch-protection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-branch-protection.js","sourceRoot":"","sources":["../src/setup-branch-protection.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsGH,4DAyFC;AA7LD,uCAAyB;AACzB,2CAA6B;AAC7B,iDAAmC;AACnC,yCAOoB;AA0BpB,MAAM,cAAc,GAAG,kBAAkB,CAAC;AAE1C,SAAS,sBAAsB,CAC7B,GAAW,EACX,KAAa,EACb,IAAY,EACZ,MAAc;IAEd,IAAI,CAAC;QACH,OAAO,IAAA,gBAAK,EAAC,SAAS,KAAK,IAAI,IAAI,aAAa,MAAM,aAAa,EAAE;YACnE,GAAG;YACH,MAAM,EAAE,KAAK;SACd,CAAsB,CAAC;IAC1B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,kBAAO,IAAI,CAAC,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;YACjD,0DAA0D;YAC1D,sDAAsD;YACtD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CACnB,QAAkC,EAClC,IAA+B;IAE/B,mFAAmF;IACnF,MAAM,cAAc,GAAG,QAAQ,EAAE,sBAAsB,EAAE,QAAQ,IAAI,EAAE,CAAC;IACxE,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK;QAC7B,CAAC,CAAC,CAAC,cAAc,CAAC;QAClB,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IAEtD,6EAA6E;IAC7E,0EAA0E;IAC1E,IAAI,OAAO,GAAuD,IAAI,CAAC;IACvE,IAAI,IAAI,CAAC,cAAc,KAAK,SAAS,IAAI,IAAI,CAAC,cAAc,GAAG,CAAC,EAAE,CAAC;QACjE,OAAO,GAAG;YACR,qBAAqB,EAAE,KAAK;YAC5B,0BAA0B,EAAE,KAAK;YACjC,+BAA+B,EAAE,IAAI,CAAC,cAAc;SACrD,CAAC;IACJ,CAAC;SAAM,IAAI,QAAQ,EAAE,6BAA6B,EAAE,CAAC;QACnD,OAAO,GAAG,QAAQ,CAAC,6BAA6B,CAAC;IACnD,CAAC;IAED,OAAO;QACL,sBAAsB,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE;QACjE,cAAc,EAAE,QAAQ,EAAE,cAAc,IAAI,KAAK;QACjD,6BAA6B,EAAE,OAAO;QACtC,YAAY,EAAE,IAAI,EAAE,kDAAkD;KACvE,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAW;IACpC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE,sBAAsB,CAAC,CAAC;IAC9E,OAAO,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAEM,KAAK,UAAU,wBAAwB,CAC5C,GAAW,EACX,OAAkC,EAAE;IAEpC,MAAM,CAAC,MAAM,CAAC,oCAAoC,CAAC,CAAC;IAEpD,IAAI,CAAC,IAAA,yBAAc,EAAC,yBAAyB,CAAC,EAAE,CAAC;QAC/C,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,IAAI,SAAS,CAAC;IACd,IAAI,CAAC;QACH,SAAS,GAAG,IAAA,2BAAgB,EAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,kBAAO,EAAE,CAAC;YACzB,OAAO,CAAC,QAAQ,GAAG,IAAA,wBAAa,EAAC,CAAC,EAAE,cAAc,CAAC,CAAC;YACpD,OAAO;QACT,CAAC;QACD,MAAM,CAAC,CAAC;IACV,CAAC;IACD,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC;IAElC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAA,+BAAoB,EAAC,GAAG,CAAC,CAAC;IAExD,qEAAqE;IACrE,uDAAuD;IACvD,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,CAAC,IAAI,CACT,8EAA8E;YAC5E,sDAAsD,CACzD,CAAC;QACF,MAAM,CAAC,GAAG,CAAC,2EAA2E,CAAC,CAAC;QACxF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,oCAAoC,KAAK,IAAI,IAAI,IAAI,MAAM,KAAK,CAAC,CAAC;IAC9E,IAAI,QAAQ,CAAC;IACb,IAAI,CAAC;QACH,QAAQ,GAAG,sBAAsB,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC9D,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,kBAAO,EAAE,CAAC;YACzB,OAAO,CAAC,QAAQ,GAAG,IAAA,wBAAa,EAAC,CAAC,EAAE,0BAA0B,CAAC,CAAC;YAChE,OAAO;QACT,CAAC;QACD,MAAM,CAAC,CAAC;IACV,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CACT,aAAa,QAAQ,CAAC,sBAAsB,EAAE,QAAQ,CAAC,MAAM,IAAI,CAAC,+BAA+B;YAC/F,oBACE,QAAQ,CAAC,sBAAsB,EAAE,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC;gBAChE,CAAC,CAAC,iBAAiB;gBACnB,CAAC,CAAC,mBACN,GAAG,CACN,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,IAAI,CAAC,kFAAkF,CAAC,CAAC;IAClG,CAAC;IAED,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC7C,MAAM,CAAC,IAAI,CACT,2CAA2C,OAAO,CAAC,sBAAsB,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;QACjG,sBAAsB,OAAO,CAAC,6BAA6B,EAAE,+BAA+B,IAAI,CAAC,GAAG,CACvG,CAAC;IAEF,IAAI,CAAC;QACH,IAAA,gBAAK,EAAC,SAAS,KAAK,IAAI,IAAI,aAAa,MAAM,aAAa,EAAE;YAC5D,GAAG;YACH,MAAM,EAAE,KAAK;YACb,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;SACnC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,kBAAO,EAAE,CAAC;YACzB,OAAO,CAAC,QAAQ,GAAG,IAAA,wBAAa,EAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC;YACxD,OAAO;QACT,CAAC;QACD,MAAM,CAAC,CAAC;IACV,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU;IAC3B,MAAM,CAAC,OAAO,CAAC,gCAAgC,KAAK,IAAI,IAAI,IAAI,MAAM,GAAG,CAAC,CAAC;IAC3E,MAAM,CAAC,GAAG,CAAC,kCAAkC,KAAK,IAAI,IAAI,oBAAoB,CAAC,CAAC;IAChF,IAAI,CAAC,OAAO,CAAC,6BAA6B,EAAE,CAAC;QAC3C,MAAM,CAAC,GAAG,CACR,oFAAoF,CACrF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/setup-gh.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared helpers for the `setup-branch-protection` and `setup-prebuild`
+ * CLI subcommands. Both wrap GitHub API calls behind `gh api` for the
+ * common path, with consistent detection / error messaging / repo
+ * resolution. Co-locating the shared surface keeps the two subcommand
+ * modules focused on payload construction.
+ */
+export interface OwnerRepo {
+    owner: string;
+    repo: string;
+}
+export declare class GhError extends Error {
+    readonly httpStatus?: number;
+    readonly suggestion?: string;
+    constructor(message: string, opts?: {
+        httpStatus?: number;
+        suggestion?: string;
+    });
+}
+/**
+ * Returns true if `gh` is on PATH and authenticated.
+ *
+ * Both setup-branch-protection and setup-prebuild require the gh CLI
+ * (we don't ship an octokit-based fallback in 2.5.2 — keeps the
+ * dependency surface narrow). Future octokit fallback would slot in
+ * here without changing callers.
+ */
+export declare function ghCliAvailable(): boolean;
+/**
+ * Resolve the owner+repo of the current git working tree using
+ * `gh repo view --json owner,name`. Requires gh to be authenticated
+ * AND the repo to have a github.com remote configured (gh respects
+ * the same git-remote conventions).
+ *
+ * Throws GhError with actionable suggestion on every failure path so
+ * the callers can render a clean error to the customer.
+ */
+export declare function resolveOwnerRepo(cwd: string): OwnerRepo;
+/**
+ * Resolve the repo's default branch via `gh repo view --json
+ * defaultBranchRef`. Used as the default `--branch` when the customer
+ * doesn't pass one explicitly — most repos use `main` but legacy
+ * repos may still default to `master` etc.
+ */
+export declare function resolveDefaultBranch(cwd: string): string;
+/**
+ * Call `gh api` with the given args and return the parsed JSON body.
+ * Throws GhError with the parsed HTTP status when the call fails so
+ * callers can branch on 403 / 404 / 422 specifically.
+ *
+ * `args` should NOT include the `-X METHOD` flag — pass it via
+ * `opts.method`. The endpoint is added at the end.
+ */
+export declare function ghApi(endpoint: string, opts: {
+    cwd: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    inputJson?: string;
+    extraArgs?: string[];
+}): unknown;
+/**
+ * Render a GhError to the customer. Returns the exit code the CLI
+ * should use (always 1 for now, but kept as a separate return for
+ * future "warn but don't fail" cases).
+ */
+export declare function renderGhError(err: GhError, context: string): number;
+/**
+ * Pre-flight check shared by both setup commands. Verifies gh CLI is
+ * available + authenticated. Renders the manual-fallback instructions
+ * if gh is missing rather than throwing — keeps the customer's
+ * troubleshooting path consistent.
+ *
+ * Returns true if pre-flight passes; false (with rendered error) if not.
+ */
+export declare function preflightGhCli(commandName: string): boolean;
+//# sourceMappingURL=setup-gh.d.ts.map

package/dist/setup-gh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-gh.d.ts","sourceRoot":"","sources":["../src/setup-gh.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,OAAQ,SAAQ,KAAK;IAChC,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpC,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;CAMjF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAQxC;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CA4BvD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAaxD;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IACJ,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,GACA,OAAO,CAmCT;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAInE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAM3D"}

package/dist/setup-gh.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Shared helpers for the `setup-branch-protection` and `setup-prebuild`
+ * CLI subcommands. Both wrap GitHub API calls behind `gh api` for the
+ * common path, with consistent detection / error messaging / repo
+ * resolution. Co-locating the shared surface keeps the two subcommand
+ * modules focused on payload construction.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GhError = void 0;
+exports.ghCliAvailable = ghCliAvailable;
+exports.resolveOwnerRepo = resolveOwnerRepo;
+exports.resolveDefaultBranch = resolveDefaultBranch;
+exports.ghApi = ghApi;
+exports.renderGhError = renderGhError;
+exports.preflightGhCli = preflightGhCli;
+const child_process_1 = require("child_process");
+const logger = __importStar(require("./logger"));
+class GhError extends Error {
+    httpStatus;
+    suggestion;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'GhError';
+        this.httpStatus = opts?.httpStatus;
+        this.suggestion = opts?.suggestion;
+    }
+}
+exports.GhError = GhError;
+/**
+ * Returns true if `gh` is on PATH and authenticated.
+ *
+ * Both setup-branch-protection and setup-prebuild require the gh CLI
+ * (we don't ship an octokit-based fallback in 2.5.2 — keeps the
+ * dependency surface narrow). Future octokit fallback would slot in
+ * here without changing callers.
+ */
+function ghCliAvailable() {
+    try {
+        (0, child_process_1.execSync)('gh --version', { stdio: 'pipe' });
+        (0, child_process_1.execSync)('gh auth status', { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the owner+repo of the current git working tree using
+ * `gh repo view --json owner,name`. Requires gh to be authenticated
+ * AND the repo to have a github.com remote configured (gh respects
+ * the same git-remote conventions).
+ *
+ * Throws GhError with actionable suggestion on every failure path so
+ * the callers can render a clean error to the customer.
+ */
+function resolveOwnerRepo(cwd) {
+    try {
+        const out = (0, child_process_1.execSync)('gh repo view --json owner,name', {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            encoding: 'utf-8',
+        });
+        const parsed = JSON.parse(out);
+        if (!parsed.owner?.login || !parsed.name) {
+            throw new GhError('gh repo view returned an unexpected payload — re-run `gh auth login`.');
+        }
+        return { owner: parsed.owner.login, repo: parsed.name };
+    }
+    catch (e) {
+        if (e instanceof GhError)
+            throw e;
+        const msg = e.stderr?.toString() ?? e.message;
+        if (msg.includes('not a git repository') || msg.includes('no remote')) {
+            throw new GhError('Repo has no github.com remote configured. Add the remote and push first.', {
+                suggestion: 'git remote add origin git@github.com:OWNER/REPO.git && git push -u origin main',
+            });
+        }
+        throw new GhError(`Could not resolve repo via gh: ${msg.trim().split('\n')[0]}`, {
+            suggestion: 'Run `gh auth login` and confirm `gh repo view` works.',
+        });
+    }
+}
+/**
+ * Resolve the repo's default branch via `gh repo view --json
+ * defaultBranchRef`. Used as the default `--branch` when the customer
+ * doesn't pass one explicitly — most repos use `main` but legacy
+ * repos may still default to `master` etc.
+ */
+function resolveDefaultBranch(cwd) {
+    try {
+        const out = (0, child_process_1.execSync)('gh repo view --json defaultBranchRef', {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            encoding: 'utf-8',
+        });
+        const parsed = JSON.parse(out);
+        if (parsed.defaultBranchRef?.name)
+            return parsed.defaultBranchRef.name;
+    }
+    catch {
+        /* fall through to fallback */
+    }
+    return 'main';
+}
+/**
+ * Call `gh api` with the given args and return the parsed JSON body.
+ * Throws GhError with the parsed HTTP status when the call fails so
+ * callers can branch on 403 / 404 / 422 specifically.
+ *
+ * `args` should NOT include the `-X METHOD` flag — pass it via
+ * `opts.method`. The endpoint is added at the end.
+ */
+function ghApi(endpoint, opts) {
+    const args = ['api'];
+    if (opts.method && opts.method !== 'GET')
+        args.push('-X', opts.method);
+    if (opts.inputJson)
+        args.push('--input', '-');
+    if (opts.extraArgs)
+        args.push(...opts.extraArgs);
+    args.push(endpoint);
+    try {
+        const out = (0, child_process_1.execSync)(`gh ${args.map((a) => JSON.stringify(a)).join(' ')}`, {
+            cwd: opts.cwd,
+            stdio: opts.inputJson ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
+            encoding: 'utf-8',
+            input: opts.inputJson,
+        });
+        return out.trim() ? JSON.parse(out) : null;
+    }
+    catch (e) {
+        const stderr = (e.stderr?.toString() ?? '').trim();
+        const statusMatch = stderr.match(/HTTP (\d+):/);
+        const httpStatus = statusMatch ? parseInt(statusMatch[1], 10) : undefined;
+        if (httpStatus === 403) {
+            throw new GhError('Permission denied — you need admin rights on the repo.', {
+                httpStatus,
+                suggestion: 'Ask a repo admin to run this command, or configure manually in repo Settings.',
+            });
+        }
+        if (httpStatus === 404) {
+            throw new GhError('Endpoint not found — repo may not exist or you may lack access.', {
+                httpStatus,
+                suggestion: 'Verify the repo via `gh repo view`.',
+            });
+        }
+        throw new GhError(`gh api failed (HTTP ${httpStatus ?? '?'}): ${stderr.split('\n')[0]}`, {
+            httpStatus,
+        });
+    }
+}
+/**
+ * Render a GhError to the customer. Returns the exit code the CLI
+ * should use (always 1 for now, but kept as a separate return for
+ * future "warn but don't fail" cases).
+ */
+function renderGhError(err, context) {
+    logger.fail(`${context}: ${err.message}`);
+    if (err.suggestion)
+        logger.dim(`  → ${err.suggestion}`);
+    return 1;
+}
+/**
+ * Pre-flight check shared by both setup commands. Verifies gh CLI is
+ * available + authenticated. Renders the manual-fallback instructions
+ * if gh is missing rather than throwing — keeps the customer's
+ * troubleshooting path consistent.
+ *
+ * Returns true if pre-flight passes; false (with rendered error) if not.
+ */
+function preflightGhCli(commandName) {
+    if (ghCliAvailable())
+        return true;
+    logger.fail(`${commandName}: gh CLI not available or not authenticated.`);
+    logger.dim('  → Install gh: https://cli.github.com');
+    logger.dim('  → Authenticate: `gh auth login`');
+    return false;
+}
+//# sourceMappingURL=setup-gh.js.map

package/dist/setup-gh.js.map

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

package/dist/setup-prebuild.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `vyuh-dxkit setup-prebuild` — configures GitHub Codespaces prebuilds
+ * for the repo, so fresh Codespaces start from a prebuilt image
+ * instead of re-running the full devcontainer build.
+ *
+ * Math: dxkit's polyglot devcontainer takes ~7 min cold-start (post per-
+ * stack feature work in Sprint 1). Prebuilds drop this to ~30s by
+ * maintaining the built image in GitHub's image cache. Storage cost
+ * ~$3-5/month per region; for a 20-dev team averaging 5 fresh
+ * Codespaces/week, the wall-clock savings dwarf the cost by 2-3 orders
+ * of magnitude.
+ *
+ * Wraps `gh api -X POST repos/{owner}/{repo}/codespaces/prebuilds` with
+ * a JSON payload defining branch + region + retention. Edge cases:
+ *   - gh CLI missing → preflight fails
+ *   - No .devcontainer/ → fail with "run init --with-devcontainer first"
+ *   - Org Codespaces disabled → HTTP 403 / 422 with org-admin guidance
+ *   - Existing prebuild config for the same branch → skip with notice
+ *     (idempotency; avoids accidental clobber of customer-chosen regions)
+ */
+export interface SetupPrebuildOpts {
+    /** Branch to prebuild. Defaults to the repo's default branch. */
+    branch?: string;
+    /**
+     * Region(s) to prebuild in. If undefined, GitHub picks a reasonable
+     * default (typically the customer's nearest region based on their
+     * Codespaces preferences). Comma-separated list when multiple.
+     */
+    regions?: string;
+    /** Force re-create even if a prebuild config exists for the branch. */
+    force?: boolean;
+}
+export declare function runSetupPrebuild(cwd: string, opts?: SetupPrebuildOpts): Promise<void>;
+//# sourceMappingURL=setup-prebuild.d.ts.map

package/dist/setup-prebuild.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-prebuild.d.ts","sourceRoot":"","sources":["../src/setup-prebuild.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAcH,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAuCD,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoH/F"}