@deftai/directive-core 0.80.0 → 0.82.0

package/dist/policy/product-signal.js

@@ -0,0 +1,210 @@
+import { readFileSync } from "node:fs";
+import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
+import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
+import { policyColonInvocation } from "./policy-invocation.js";
+import { appendAuditLog, loadProjectDefinition, projectDefinitionPath } from "./resolve.js";
+/** Canonical registered policy field name (#2693). */
+export const FIELD_PRODUCT_SIGNAL = "plan.policy.productSignal";
+/** Short alias for `policy:show --field=productSignal`. */
+export const FIELD_PRODUCT_SIGNAL_CLI_ALIAS = "productSignal";
+export const DEFAULT_PRODUCT_SIGNAL_ENABLED = false;
+/** Baked-in default private sink (#2693 D6). */
+export const DEFAULT_PRODUCT_SIGNAL_SINK_REPO = "deftai/product-signal";
+export const PRODUCT_SIGNAL_CAPABILITY_COST_DISCLOSURE = "\u26a0 Capability-cost disclosure -- enabling product signal opts into " +
+    "consented qualitative check-ins that may submit minimized local summaries " +
+    "to a private GitHub sink when you also grant install-level consent.\n" +
+    "  \u2022 Default OFF; no ambient consent nag while disabled.\n" +
+    "  \u2022 Outbound requires enable + recorded consent (`product-signal:consent`).\n" +
+    "  \u2022 Payloads include install context and windowed value/health/helped summaries " +
+    "(not raw ledgers or chat).\n" +
+    "  \u2022 Inspect: `" +
+    policyColonInvocation("show", " --field=productSignal") +
+    "` and `task product-signal:status`.\n" +
+    "  \u2022 Reversible: set `enabled: false` or revoke consent.\n" +
+    "  \u2022 Changes are recorded to meta/policy-changes.log for auditability.";
+function defaultResolved(source, error = null) {
+    return {
+        enabled: DEFAULT_PRODUCT_SIGNAL_ENABLED,
+        sinkRepo: DEFAULT_PRODUCT_SIGNAL_SINK_REPO,
+        source,
+        error,
+    };
+}
+/** Validate a `plan.policy.productSignal` payload. */
+export function validateProductSignal(value) {
+    if (value === null || value === undefined) {
+        return [];
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return [`${FIELD_PRODUCT_SIGNAL} must be an object; got ${typeof value}`];
+    }
+    const rec = value;
+    const errors = [];
+    if ("enabled" in rec && typeof rec.enabled !== "boolean") {
+        errors.push(`${FIELD_PRODUCT_SIGNAL}.enabled must be a boolean`);
+    }
+    if ("sinkRepo" in rec && typeof rec.sinkRepo !== "string") {
+        errors.push(`${FIELD_PRODUCT_SIGNAL}.sinkRepo must be a string`);
+    }
+    return errors;
+}
+function resolveFromPolicyBlock(raw) {
+    const errors = validateProductSignal(raw);
+    if (errors.length > 0) {
+        return defaultResolved("default-on-error", errors[0] ?? "invalid productSignal block");
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return defaultResolved("default");
+    }
+    const block = raw;
+    const enabled = typeof block.enabled === "boolean" ? block.enabled : DEFAULT_PRODUCT_SIGNAL_ENABLED;
+    const sinkRepo = typeof block.sinkRepo === "string" && block.sinkRepo.trim().length > 0
+        ? block.sinkRepo.trim()
+        : DEFAULT_PRODUCT_SIGNAL_SINK_REPO;
+    return {
+        enabled,
+        sinkRepo,
+        source: "typed",
+        error: null,
+    };
+}
+/** Resolve `plan.policy.productSignal` from PROJECT-DEFINITION (#2693). */
+export function resolveProductSignal(projectRoot) {
+    const [data, err] = loadProjectDefinition(projectRoot);
+    if (data === null) {
+        return defaultResolved("default-on-error", err);
+    }
+    const policyBlock = readPlanPolicy(data.plan);
+    if (typeof policyBlock !== "object" ||
+        policyBlock === null ||
+        Array.isArray(policyBlock) ||
+        !("productSignal" in policyBlock)) {
+        return defaultResolved("default");
+    }
+    return resolveFromPolicyBlock(policyBlock.productSignal);
+}
+/** Human-readable status line for CLI surfaces. */
+export function formatProductSignalStatusLine(policy) {
+    return (`[deft policy] productSignal enabled=${String(policy.enabled)} ` +
+        `sinkRepo=${policy.sinkRepo}.`);
+}
+function fieldFromResolved(resolved) {
+    return {
+        name: FIELD_PRODUCT_SIGNAL,
+        current: {
+            enabled: resolved.enabled,
+            sinkRepo: resolved.sinkRepo,
+        },
+        default: {
+            enabled: DEFAULT_PRODUCT_SIGNAL_ENABLED,
+            sinkRepo: DEFAULT_PRODUCT_SIGNAL_SINK_REPO,
+        },
+        source: resolved.source,
+    };
+}
+/** Inspector row for `policy:show --field=productSignal`. */
+export function inspectProductSignal(data, projectRoot) {
+    if (data === null) {
+        return fieldFromResolved(defaultResolved("default"));
+    }
+    const policyBlock = readPlanPolicy(data.plan);
+    if (typeof policyBlock !== "object" ||
+        policyBlock === null ||
+        Array.isArray(policyBlock) ||
+        !("productSignal" in policyBlock)) {
+        if (projectRoot !== undefined) {
+            return fieldFromResolved(resolveProductSignal(projectRoot));
+        }
+        return fieldFromResolved(defaultResolved("default"));
+    }
+    return fieldFromResolved(resolveFromPolicyBlock(policyBlock.productSignal));
+}
+/** Persist `productSignal.enabled=true` after capability-cost disclosure (#2693). */
+export function enableProductSignal(projectRoot, options) {
+    if (!options.confirm) {
+        return {
+            exitCode: 1,
+            stdout: `${PRODUCT_SIGNAL_CAPABILITY_COST_DISCLOSURE}\n\n` +
+                `Re-run with --confirm to apply: task product-signal:enable -- --confirm\n`,
+            changed: false,
+        };
+    }
+    const path = projectDefinitionPath(projectRoot);
+    try {
+        const { changed } = projectDefinitionMutationLock(projectRoot, () => {
+            const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
+            }
+            const data = parsed;
+            if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
+                if (data.plan === undefined) {
+                    data.plan = {};
+                }
+                else {
+                    throw new Error("PROJECT-DEFINITION 'plan' is not an object");
+                }
+            }
+            const plan = data.plan;
+            migrateLegacyPolicyKey(plan);
+            const existingPolicy = plan[PLAN_POLICY_KEY];
+            if (typeof existingPolicy !== "object" ||
+                existingPolicy === null ||
+                Array.isArray(existingPolicy)) {
+                if (existingPolicy === undefined) {
+                    plan[PLAN_POLICY_KEY] = {};
+                }
+                else {
+                    throw new Error("plan.policy is not an object");
+                }
+            }
+            const policyBlock = plan[PLAN_POLICY_KEY];
+            const previous = policyBlock.productSignal;
+            const prevObj = typeof previous === "object" && previous !== null && !Array.isArray(previous)
+                ? previous
+                : {};
+            const sinkRepo = options.sinkRepo?.trim() ||
+                (typeof prevObj.sinkRepo === "string" && prevObj.sinkRepo.trim().length > 0
+                    ? prevObj.sinkRepo.trim()
+                    : DEFAULT_PRODUCT_SIGNAL_SINK_REPO);
+            const nextBlock = { enabled: true, sinkRepo };
+            const previousNormalized = resolveFromPolicyBlock(previous);
+            const changedFlag = previousNormalized.enabled !== nextBlock.enabled ||
+                previousNormalized.sinkRepo !== nextBlock.sinkRepo;
+            policyBlock.productSignal = nextBlock;
+            if (changedFlag) {
+                atomicWriteProjectDefinition(path, data);
+            }
+            const actor = options.actor ?? "task product-signal:enable";
+            const note = options.note ?? "";
+            const parts = [
+                `actor=${actor}`,
+                "productSignal.enabled=true",
+                `sinkRepo=${sinkRepo}`,
+                `previous=${JSON.stringify(previous ?? null)}`,
+            ];
+            if (note) {
+                parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
+            }
+            appendAuditLog(projectRoot, parts.join(" "));
+            return { changed: changedFlag };
+        });
+        const resolved = resolveProductSignal(projectRoot);
+        const lines = [
+            `\u2713 ${FIELD_PRODUCT_SIGNAL}.enabled=true (product-signal ON).`,
+            changed
+                ? "  audit: meta/policy-changes.log updated."
+                : "  no-op: value already matched (audit entry still appended for trail).",
+            formatProductSignalStatusLine(resolved),
+        ];
+        return { exitCode: 0, stdout: `${lines.join("\n")}\n`, changed };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("PROJECT-DEFINITION not found")) {
+            return { exitCode: 2, stdout: `\u274c ${message}\n`, changed: false };
+        }
+        return { exitCode: 2, stdout: `\u274c Config error: ${message}\n`, changed: false };
+    }
+}
+//# sourceMappingURL=product-signal.js.map

package/dist/pr-wait-mergeable/cascade.d.ts

@@ -1,8 +1,16 @@
+import { type SemanticGreenFn } from "./semantic-green.js";
 import type { MergeFn, MonitorFn, ProtectedCheckFn, WaitMergeableResult } from "./types.js";
 export interface WaitMergeableOptions {
     readonly protectedFn?: ProtectedCheckFn;
     readonly monitorFn?: MonitorFn;
     readonly mergeFn?: MergeFn;
+    readonly semanticGreenFn?: SemanticGreenFn;
+    /** Enable merge-cascade semantic-green gate (#2385). */
+    readonly cascadeMode?: boolean;
+    /** After a prior cascade merge, require target-branch CI green at HEAD. */
+    readonly requireMasterCiGreen?: boolean;
+    /** Target branch override for stale-base comparison (defaults to PR base.ref). */
+    readonly baseBranch?: string | null;
 }
 /** Run protected-check -> wait -> merge cascade (#1369). */
 export declare function waitMergeableAndMerge(prNumber: number, repo: string, options: {

package/dist/pr-wait-mergeable/cascade.js

@@ -1,6 +1,7 @@
 import { classifyMonitorOutcome, parseMonitorPayload } from "./classify.js";
 import { EXIT_CONFIG_ERROR, EXIT_MERGED, EXIT_TIMEOUT_OR_ESCALATION } from "./constants.js";
 import { makeResult } from "./result.js";
+import { evaluateSemanticGreen } from "./semantic-green.js";
 import { runGhMerge, runMonitor, runProtectedCheck } from "./wrappers.js";
 /** Node module-not-found / missing script — not a protected-issue overlap (#2667). */
 function isProtectedCheckConfigFailure(stderr) {
@@ -14,6 +15,7 @@ export function waitMergeableAndMerge(prNumber, repo, options) {
     const protectedFn = options.protectedFn ?? runProtectedCheck;
     const monitorFn = options.monitorFn ?? runMonitor;
     const mergeFn = options.mergeFn ?? runGhMerge;
+    const semanticGreenFn = options.semanticGreenFn ?? evaluateSemanticGreen;
     const protectedIssues = options.protected;
     let protectedCheckPayload = {};
     if (protectedIssues.length > 0) {
@@ -47,6 +49,22 @@ export function waitMergeableAndMerge(prNumber, repo, options) {
             });
         }
     }
+    const semanticGreen = semanticGreenFn(prNumber, repo, {
+        cascadeMode: options.cascadeMode,
+        requireMasterCiGreen: options.requireMasterCiGreen,
+        baseBranch: options.baseBranch,
+    });
+    if (!semanticGreen.ok) {
+        return makeResult({
+            prNumber,
+            repo,
+            outcome: semanticGreen.outcome ?? "semantic-green-blocked",
+            exitCode: semanticGreen.exitCode ?? EXIT_TIMEOUT_OR_ESCALATION,
+            protectedCheck: protectedCheckPayload,
+            semanticGreen: { ...semanticGreen.payload },
+            error: semanticGreen.error,
+        });
+    }
     const [monRc, monStdout, monStderr] = monitorFn(prNumber, repo, options.capMinutes);
     const monitorPayload = parseMonitorPayload(monStdout);
     const [outcome, monitorExit] = classifyMonitorOutcome(monRc, monitorPayload);

package/dist/pr-wait-mergeable/main.d.ts

@@ -5,6 +5,9 @@ export interface ParsedWaitMergeableArgs {
     readonly capMinutes: number;
     readonly protectedValues: readonly string[];
     readonly emitJson: boolean;
+    readonly cascadeMode: boolean;
+    readonly requireMasterCiGreen: boolean;
+    readonly baseBranch: string | null;
     readonly error?: string;
 }
 export declare function parseWaitMergeableArgs(argv: readonly string[]): ParsedWaitMergeableArgs;
@@ -12,6 +15,7 @@ export interface RunWaitMergeableOptions {
     readonly protectedFn?: Parameters<typeof waitMergeableAndMerge>[2]["protectedFn"];
     readonly monitorFn?: Parameters<typeof waitMergeableAndMerge>[2]["monitorFn"];
     readonly mergeFn?: Parameters<typeof waitMergeableAndMerge>[2]["mergeFn"];
+    readonly semanticGreenFn?: Parameters<typeof waitMergeableAndMerge>[2]["semanticGreenFn"];
 }
 export declare function runWaitMergeable(argv: readonly string[], options?: RunWaitMergeableOptions): number;
 export declare function cmdPrWaitMergeable(argv: readonly string[], options?: RunWaitMergeableOptions): number;

package/dist/pr-wait-mergeable/main.js

@@ -16,22 +16,45 @@ export function parseWaitMergeableArgs(argv) {
     let capMinutes = 60;
     const protectedValues = [];
     let emitJson = false;
+    let cascadeMode = false;
+    let requireMasterCiGreen = false;
+    let baseBranch = null;
+    const baseReturn = () => ({
+        prNumber,
+        repo,
+        capMinutes,
+        protectedValues,
+        emitJson,
+        cascadeMode,
+        requireMasterCiGreen,
+        baseBranch,
+    });
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === "--json") {
             emitJson = true;
         }
+        else if (arg === "--cascade") {
+            cascadeMode = true;
+        }
+        else if (arg === "--require-master-ci-green") {
+            requireMasterCiGreen = true;
+        }
+        else if (arg === "--base-branch") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...baseReturn(), error: "argument --base-branch: expected one argument" };
+            }
+            baseBranch = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--base-branch=")) {
+            baseBranch = arg.slice("--base-branch=".length);
+        }
         else if (arg === "--repo") {
             const value = argv[i + 1];
             if (value === undefined) {
-                return {
-                    prNumber,
-                    repo,
-                    capMinutes,
-                    protectedValues,
-                    emitJson,
-                    error: "argument --repo: expected one argument",
-                };
+                return { ...baseReturn(), error: "argument --repo: expected one argument" };
             }
             repo = value;
             i += 1;
@@ -42,25 +65,11 @@ export function parseWaitMergeableArgs(argv) {
         else if (arg === "--cap-minutes") {
             const value = argv[i + 1];
             if (value === undefined) {
-                return {
-                    prNumber,
-                    repo,
-                    capMinutes,
-                    protectedValues,
-                    emitJson,
-                    error: "argument --cap-minutes: expected one argument",
-                };
+                return { ...baseReturn(), error: "argument --cap-minutes: expected one argument" };
             }
             const parsed = Number(value);
             if (!Number.isFinite(parsed)) {
-                return {
-                    prNumber,
-                    repo,
-                    capMinutes,
-                    protectedValues,
-                    emitJson,
-                    error: `invalid --cap-minutes value: ${value}`,
-                };
+                return { ...baseReturn(), error: `invalid --cap-minutes value: ${value}` };
             }
             capMinutes = parsed;
             i += 1;
@@ -69,28 +78,14 @@ export function parseWaitMergeableArgs(argv) {
             const value = arg.slice("--cap-minutes=".length);
             const parsed = Number(value);
             if (!Number.isFinite(parsed)) {
-                return {
-                    prNumber,
-                    repo,
-                    capMinutes,
-                    protectedValues,
-                    emitJson,
-                    error: `invalid --cap-minutes value: ${value}`,
-                };
+                return { ...baseReturn(), error: `invalid --cap-minutes value: ${value}` };
             }
             capMinutes = parsed;
         }
         else if (arg === "--protected") {
             const value = argv[i + 1];
             if (value === undefined) {
-                return {
-                    prNumber,
-                    repo,
-                    capMinutes,
-                    protectedValues,
-                    emitJson,
-                    error: "argument --protected: expected one argument",
-                };
+                return { ...baseReturn(), error: "argument --protected: expected one argument" };
             }
             protectedValues.push(value);
             i += 1;
@@ -99,51 +94,23 @@ export function parseWaitMergeableArgs(argv) {
             protectedValues.push(arg.slice("--protected=".length));
         }
         else if (arg?.startsWith("-")) {
-            return {
-                prNumber,
-                repo,
-                capMinutes,
-                protectedValues,
-                emitJson,
-                error: `unrecognized arguments: ${arg}`,
-            };
+            return { ...baseReturn(), error: `unrecognized arguments: ${arg}` };
         }
         else if (prNumber === null) {
             const n = Number(arg);
             if (!Number.isInteger(n)) {
-                return {
-                    prNumber,
-                    repo,
-                    capMinutes,
-                    protectedValues,
-                    emitJson,
-                    error: `invalid PR number: ${arg}`,
-                };
+                return { ...baseReturn(), error: `invalid PR number: ${arg}` };
             }
             prNumber = n;
         }
         else {
-            return {
-                prNumber,
-                repo,
-                capMinutes,
-                protectedValues,
-                emitJson,
-                error: `unrecognized arguments: ${arg}`,
-            };
+            return { ...baseReturn(), error: `unrecognized arguments: ${arg}` };
         }
     }
     if (prNumber === null) {
-        return {
-            prNumber,
-            repo,
-            capMinutes,
-            protectedValues,
-            emitJson,
-            error: "the following arguments are required: pr_number",
-        };
+        return { ...baseReturn(), error: "the following arguments are required: pr_number" };
     }
-    return { prNumber, repo, capMinutes, protectedValues, emitJson };
+    return baseReturn();
 }
 function summaryLabelForExit(exitCode) {
     switch (exitCode) {
@@ -183,6 +150,10 @@ export function runWaitMergeable(argv, options = {}) {
         protectedFn: options.protectedFn,
         monitorFn: options.monitorFn,
         mergeFn: options.mergeFn,
+        semanticGreenFn: options.semanticGreenFn,
+        cascadeMode: args.cascadeMode,
+        requireMasterCiGreen: args.requireMasterCiGreen,
+        baseBranch: args.baseBranch,
     });
     const summaryLabel = summaryLabelForExit(result.exitCode);
     process.stderr.write(`[pr_wait_mergeable] PR #${result.prNumber} repo=${result.repo} ` +

package/dist/pr-wait-mergeable/result.d.ts

@@ -1,8 +1,9 @@
 import type { WaitMergeableResult } from "./types.js";
 export declare function toResultDict(result: WaitMergeableResult): Record<string, unknown>;
-export declare function makeResult(fields: Omit<WaitMergeableResult, "monitorResult" | "protectedCheck" | "mergeStdout" | "mergeStderr"> & {
+export declare function makeResult(fields: Omit<WaitMergeableResult, "monitorResult" | "protectedCheck" | "semanticGreen" | "mergeStdout" | "mergeStderr"> & {
     readonly monitorResult?: Record<string, unknown>;
     readonly protectedCheck?: Record<string, unknown>;
+    readonly semanticGreen?: Record<string, unknown>;
     readonly mergeStdout?: string;
     readonly mergeStderr?: string;
 }): WaitMergeableResult;

package/dist/pr-wait-mergeable/result.js

@@ -11,6 +11,9 @@ export function toResultDict(result) {
     if (Object.keys(result.protectedCheck).length > 0) {
         payload.protected_check = result.protectedCheck;
     }
+    if (Object.keys(result.semanticGreen).length > 0) {
+        payload.semantic_green = result.semanticGreen;
+    }
     if (result.mergeStdout.length > 0) {
         payload.merge_stdout = result.mergeStdout;
     }
@@ -26,6 +29,7 @@ export function makeResult(fields) {
     return {
         monitorResult: fields.monitorResult ?? {},
         protectedCheck: fields.protectedCheck ?? {},
+        semanticGreen: fields.semanticGreen ?? {},
         mergeStdout: fields.mergeStdout ?? "",
         mergeStderr: fields.mergeStderr ?? "",
         prNumber: fields.prNumber,

package/dist/pr-wait-mergeable/semantic-green.d.ts

@@ -0,0 +1,27 @@
+import type { RunGhFn } from "../pr-merge-readiness/types.js";
+export interface SemanticGreenOptions {
+    /** Enable merge-cascade semantic-green checks (#2385). */
+    readonly cascadeMode?: boolean;
+    /** After a prior cascade merge, require target-branch CI green at HEAD before the next merge. */
+    readonly requireMasterCiGreen?: boolean;
+    /** Target branch for stale-base comparison (defaults to PR base.ref). */
+    readonly baseBranch?: string | null;
+    readonly runGh?: RunGhFn;
+}
+export interface SemanticGreenPayload {
+    readonly pr_base_sha: string | null;
+    readonly target_branch: string | null;
+    readonly target_head_sha: string | null;
+    readonly master_ci: Record<string, unknown>;
+}
+export interface SemanticGreenResult {
+    readonly ok: boolean;
+    readonly outcome: string | null;
+    readonly exitCode: number | null;
+    readonly error: string | null;
+    readonly payload: SemanticGreenPayload;
+}
+/** Pre-merge semantic-green gate for merge cascades (#2385). */
+export declare function evaluateSemanticGreen(prNumber: number, repo: string, options?: SemanticGreenOptions): SemanticGreenResult;
+export type SemanticGreenFn = typeof evaluateSemanticGreen;
+//# sourceMappingURL=semantic-green.d.ts.map