@pareto4/pp-core 1.9.0 → 1.11.0

package/pp-core/bin/lib/git-provider.cjs

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * src/git-provider.cts — the provider seam (milestone v1.11.0, Phase 30-01;
+ * org-profile layer added Phase 33-03).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the git-ignored `pp-core/bin/lib/git-provider.cjs`; do NOT
+ * hand-edit the compiled output. Behaviour is locked by
+ * `tests/git-provider.test.cjs`.
+ *
+ * This module is the single place every git-host decision in pp-core routes
+ * through: which provider is configured, whether a value is already a literal
+ * clone target, how a `group/project` slug composes into a clone URL for that
+ * provider, what environment a clone needs, and whether a host CLI (`glab`)
+ * may be spawned at all. It imports node builtins plus `./org-profile.cjs` —
+ * still never `./vault.cjs`, `./vault-coordinates.cjs`, `./io.cjs` or
+ * `./shell-command-projection.cjs` — so that both `src/vault.cts` and
+ * `src/vault-write-back.cts` can import it (since 30-02 and 30-03) without
+ * forming a require cycle in the CommonJS graph `require()` loads.
+ * `./org-profile.cjs` is the one exception: it is itself a zero-import leaf
+ * (node builtins only, see its own header), so importing it here creates no
+ * load-time cycle even though it lazily requires this module back at
+ * call-time for `normalizeProvider`/`PROVIDERS` reuse (D-10).
+ *
+ * This plan (30-01) produced no behaviour change on its own: nothing called
+ * this module at the time. 33-03 is the first plan to change `resolveProvider`
+ * itself, adding the org-profile consultation between the config read and
+ * `DEFAULT_PROVIDER` (D-07).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LITERAL_CLONE_TARGET_PATTERNS = exports.PROVIDER_CONFIG_KEY = exports.DEFAULT_PROVIDER = exports.PROVIDERS = void 0;
+exports.normalizeProvider = normalizeProvider;
+exports.resolveProvider = resolveProvider;
+exports.isLiteralCloneTarget = isLiteralCloneTarget;
+exports.composeCloneTarget = composeCloneTarget;
+exports.cloneEnv = cloneEnv;
+exports.providerUsesHostCli = providerUsesHostCli;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const org_profile_cjs_1 = require("./org-profile.cjs");
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** The complete, ordered set of supported provider ids. */
+exports.PROVIDERS = Object.freeze(['gitlab', 'azure']);
+/**
+ * Every project that has never heard of this phase resolves to this provider
+ * (PROV-04): an absent config key is the normal case, not an error.
+ */
+exports.DEFAULT_PROVIDER = 'gitlab';
+/** The dotted `.planning/config.json` key that selects the provider. */
+exports.PROVIDER_CONFIG_KEY = 'vault.provider';
+// ─── normalizeProvider ───────────────────────────────────────────────────────
+/**
+ * Normalize an arbitrary config value into a canonical `ProviderId`, or
+ * `null` if it is not an exact (case/whitespace-tolerant) member of
+ * `PROVIDERS`.
+ *
+ * Deliberately takes NO host or repo argument. That absence is what makes
+ * PROV-01's "never inferred from a hostname string" structurally true rather
+ * than a promise this function merely keeps by convention — it has nothing
+ * else to look at. Trimming and case-folding are tolerance for operator
+ * typing (`" Azure "`, `"GITLAB"`), not inference: there is no substring or
+ * prefix matching, only exact membership after normalization.
+ */
+function normalizeProvider(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.trim().toLowerCase();
+    return exports.PROVIDERS.includes(normalized) ? normalized : null;
+}
+// ─── resolveProvider ─────────────────────────────────────────────────────────
+/**
+ * Read `.planning/config.json` at `cwd`, returning `fallback` on any
+ * miss/unreadable-file/parse-error/non-object. Never throws.
+ *
+ * This mirrors `cfgGet` in `src/vault.cts` (lines 111-126) exactly, but is
+ * written inline rather than imported: `src/vault.cts` will import THIS
+ * module in 30-02, so importing `cfgGet` back from `vault.cjs` would create a
+ * cycle in the CommonJS graph loaded by `require`. The duplication is about
+ * ten lines with no behavioural variance to drift on.
+ */
+function cfgGet(cwd, key, fallback) {
+    try {
+        const cfg = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(cwd, '.planning', 'config.json'), 'utf-8'));
+        const v = key.split('.').reduce((o, k) => (o && typeof o === 'object' ? o[k] : undefined), cfg);
+        return v === undefined ? fallback : v;
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Bound a rejected config value before it is echoed into a warning. The
+ * warning is written into `.planning/vault/manifest.json` and printed by
+ * `vault status`, so an unbounded or newline-bearing config value would be a
+ * log-injection vector (T-30-04): strip CR/LF, collapse internal whitespace,
+ * then truncate to 40 characters.
+ */
+function sanitizeForWarning(value) {
+    return value.replace(/[\r\n]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 40);
+}
+/**
+ * Resolve the configured provider for the project at `cwd`, in three steps
+ * (D-07): `.planning/config.json` → the org profile → `DEFAULT_PROVIDER`.
+ *
+ * Reads `.planning/config.json`'s `vault.provider` key first — never a host,
+ * never a repo shape, never `.platform-bindings.json`. When that value is set
+ * to anything other than `undefined`/`null`/`''`, it is the operator's
+ * explicit choice and is NEVER overridden by an org profile, even when it is
+ * unrecognized (D-05): a recognized value returns with no warnings, and an
+ * unrecognized value resolves to `DEFAULT_PROVIDER` with exactly one bounded,
+ * single-line warning naming the rejected value and the two supported ids —
+ * the org profile is not consulted on this branch at all.
+ *
+ * When the config key is absent, `null` or `''` — the "not set" branch — the
+ * org profile is consulted for `vault.provider` via `readProfileValue`. When
+ * it supplies a value, that value is re-normalized here (defensively) before
+ * use; a normalized hit is returned, a miss falls through to
+ * `DEFAULT_PROVIDER`. Either way the profile layer's own `warnings` are
+ * returned unchanged and unfiltered — they are already bounded and already
+ * de-duplicated within one `readProfileValue` call. With no profile
+ * configured, `readProfileValue` returns `{ value: undefined, warnings: [] }`
+ * and this branch returns `DEFAULT_PROVIDER` with `warnings: []` — identical
+ * to the pre-33-03 early return (PROV-04 / ORG-02). This function adds no
+ * warning of its own for the no-profile case.
+ */
+function resolveProvider(cwd) {
+    const raw = cfgGet(cwd, exports.PROVIDER_CONFIG_KEY, undefined);
+    if (raw === undefined || raw === null || raw === '') {
+        const profile = (0, org_profile_cjs_1.readProfileValue)(cwd, exports.PROVIDER_CONFIG_KEY);
+        if (profile.value !== undefined) {
+            const normalizedProfileValue = normalizeProvider(profile.value);
+            if (normalizedProfileValue !== null) {
+                return { provider: normalizedProfileValue, warnings: profile.warnings };
+            }
+        }
+        return { provider: exports.DEFAULT_PROVIDER, warnings: profile.warnings };
+    }
+    const normalized = normalizeProvider(raw);
+    if (normalized !== null) {
+        return { provider: normalized, warnings: [] };
+    }
+    const rawStr = typeof raw === 'string' ? raw : JSON.stringify(raw);
+    const echoed = sanitizeForWarning(rawStr ?? '');
+    const warning = `Unrecognized ${exports.PROVIDER_CONFIG_KEY} value "${echoed}" — supported: ${exports.PROVIDERS.join(', ')}. Falling back to ${exports.DEFAULT_PROVIDER}.`;
+    return { provider: exports.DEFAULT_PROVIDER, warnings: [warning.slice(0, 120)] };
+}
+// ─── LITERAL_CLONE_TARGET_PATTERNS ──────────────────────────────────────────
+/**
+ * The single regex-expressible definition of the seven forms
+ * `isLiteralCloneTarget` accepts, as anchored regex source strings. Entry
+ * order is part of the contract: `scripts/gen-platform-bindings-schema.cjs`
+ * (plan 02) concatenates these into one alternation in this order, so a
+ * reorder here is a deliberate schema-regenerating edit, not a
+ * refactor-neutral one. `tests/git-provider.test.cjs` locks length, order and
+ * content.
+ */
+exports.LITERAL_CLONE_TARGET_PATTERNS = Object.freeze([
+    '^[A-Za-z][A-Za-z0-9+.-]*:\\/\\/', // scheme URL — e.g. https://, ssh://, file://
+    '^[\\w.][\\w.-]*@', // scp-style ssh — user@host:path
+    '^\\/', // absolute unix path
+    '^\\.\\/', // explicit relative — ./path
+    '^\\.\\.\\/', // parent-relative — ../path
+    '^~', // home-relative — ~ or ~/path
+    '^[A-Za-z]:[\\\\/]', // Windows drive path — C:\ or C:/
+]);
+// Compiled once at module load, without the global flag (a global regex
+// carries `lastIndex` state across `test` calls and would make the predicate
+// answer differently on repeated identical inputs).
+const compiledLiteralCloneTargetPatterns = exports.LITERAL_CLONE_TARGET_PATTERNS.map((source) => new RegExp(source));
+// ─── isLiteralCloneTarget (relocated verbatim from src/vault.cts) ───────────
+/**
+ * True when `value` is already something git can clone directly — an
+ * absolute path, a scheme-qualified URL, or scp-style `user@host:path` —
+ * rather than a `group/project` slug that must be composed onto a host.
+ *
+ * This is now the SINGLE definition. `src/vault.cts` and
+ * `src/vault-write-back.cts` import it from here (30-02, 30-03) rather than
+ * each keeping a copy — a read/write divergence in this predicate was defect
+ * P-1 in Phase 29 (the write path used the value verbatim while the read path
+ * always composed a URL, so a slug broke writing and a path broke reading).
+ *
+ * Security (T-29-26): a value git would read as an OPTION must never take
+ * the verbatim branch. The scheme test is anchored at the START — an earlier
+ * version used `value.includes('://')`, so `--upload-pack=…#x://` passed
+ * through as a flag — and the scp-style test may not begin with `-`. This
+ * function is also the newer half of the pair: before it existed, this path
+ * ALWAYS composed a URL, so a flag-shaped repo could not reach git here at
+ * all. Callers pass `--` before the target as the second layer.
+ *
+ * The seven forms now live in the exported `LITERAL_CLONE_TARGET_PATTERNS`
+ * array so artifacts that cannot call this function — specifically the JSON
+ * Schema `pattern` in `schemas/platform-bindings.schema.json` — can be
+ * generated from the same definition rather than hand-transcribing it. The
+ * array is consumed by `src/platform-bindings.cts` and, through it, by
+ * `scripts/gen-platform-bindings-schema.cjs` (plan 02). The leading-dash
+ * refusal below is deliberately not one of the seven entries.
+ */
+function isLiteralCloneTarget(value) {
+    if (value.startsWith('-'))
+        return false;
+    return compiledLiteralCloneTargetPatterns.some((re) => re.test(value));
+}
+// ─── composeCloneTarget ──────────────────────────────────────────────────────
+/**
+ * Compose `repo` into something `git clone` can reach for `provider` at
+ * `host`, or pass it through verbatim when it is already a literal clone
+ * target (PROV-02's final sentence — this is what keeps the working Azure
+ * SSH form `git@ssh.dev.azure.com:v3/{org}/{project}/{repo}` working
+ * unchanged).
+ *
+ * `gitlab`: `https://{host}/{slug}.git` — byte-identical to the template
+ * being removed from `src/vault.cts` in 30-02, because PROV-04 depends on
+ * this string not moving.
+ *
+ * `azure`: `https://{host}/{slug}` — no `.git` suffix appended. Azure DevOps
+ * rejects a `.git`-suffixed path (`TF401019`); this is the entire reason
+ * PROV-02 exists.
+ *
+ * When `provider` is `azure` and the trimmed slug already ends in `.git`, the
+ * suffix is NOT stripped — an operator-configured coordinate is data, not
+ * something this function rewrites — but exactly one warning is returned
+ * naming `TF401019` and recommending the suffix be removed from the
+ * configured value. Composition still never appends; the suffix in that case
+ * is the operator's own (T-30-08, accepted risk: rewriting a configured
+ * coordinate is a worse failure mode than a clear diagnostic).
+ */
+function composeCloneTarget(provider, repo, host) {
+    const trimmed = repo.trim();
+    if (isLiteralCloneTarget(trimmed)) {
+        return { url: trimmed, warnings: [] };
+    }
+    if (provider === 'azure') {
+        const url = `https://${host}/${trimmed}`;
+        if (trimmed.endsWith('.git')) {
+            return {
+                url,
+                warnings: [
+                    'Azure DevOps rejects a .git-suffixed path (TF401019) — remove the .git suffix from the configured vault repo value.',
+                ],
+            };
+        }
+        return { url, warnings: [] };
+    }
+    // gitlab (and, structurally, any future provider that composes the same
+    // shape) — byte-identical to the template this replaces.
+    return { url: `https://${host}/${trimmed}.git`, warnings: [] };
+}
+// ─── cloneEnv ────────────────────────────────────────────────────────────────
+/**
+ * Build the environment additions a clone needs for `provider` at `host`.
+ *
+ * `gitlab` needs `GITLAB_HOST` (consumed by the `glab repo clone` flow).
+ * `azure` needs nothing — an empty object.
+ *
+ * `execGit`/`execTool` (`src/shell-command-projection.cts` lines 441-446 and
+ * 473) MERGE this object over `process.env`, so the empty object for `azure`
+ * is a genuine no-op: it preserves PATH, the ambient credential helper, and
+ * the non-interactive defaults Azure authentication relies on. It does not
+ * strip anything.
+ */
+function cloneEnv(provider, host) {
+    if (provider === 'gitlab')
+        return { GITLAB_HOST: host };
+    return {};
+}
+// ─── providerUsesHostCli ─────────────────────────────────────────────────────
+/**
+ * True when `provider` has a first-class host CLI available (`glab`, for
+ * `gitlab`). Returns a boolean rather than a program name: no caller should
+ * ever build a subprocess program name out of a config-derived string, and
+ * returning a boolean makes that impossible rather than merely discouraged
+ * (T-30-03).
+ */
+function providerUsesHostCli(provider) {
+    return provider === 'gitlab';
+}