@deftai/directive-core 0.55.1 → 0.56.0

package/dist/preflight-cache/evaluate.js

@@ -13,6 +13,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
+import { probeCacheDrift } from "../cache/fetch.js";
 // ---------------------------------------------------------------------------
 // Public constants (mirror preflight_cache.py)
 // ---------------------------------------------------------------------------
@@ -246,7 +247,7 @@ function parseCandidates(candidatesPath) {
                 if (data !== null && typeof data === "object" && !Array.isArray(data)) {
                     const d = data;
                     entries.push({
-                        issue: Number(d.issue ?? 0),
+                        issue: Number(d.issue ?? d.issue_number ?? 0),
                         repo: String(d.repo ?? ""),
                         decision: String(d.decision ?? ""),
                         ts: String(d.ts ?? d.timestamp ?? ""),
@@ -272,7 +273,49 @@ function latestDecisionForIssue(candidates, repo, issueNumber) {
 // Main evaluate function
 // ---------------------------------------------------------------------------
 const REMEDIATION_NO_CACHE = ["  Recovery: run `deft triage:bootstrap` to seed the cache."].join("\n");
-const REMEDIATION_STALE = ["  Recovery: run `deft cache:fetch-all` to refresh the cache."].join("\n");
+const REMEDIATION_STALE_FORCE = [
+    "  Recovery: run `deft cache:fetch-all --force` to refresh and reconcile upstream state.",
+].join("\n");
+const REMEDIATION_STALE_PLAIN = [
+    "  Recovery: run `deft cache:fetch-all` to refresh and reconcile upstream state.",
+].join("\n");
+/**
+ * Branch-aware recovery hint (#1953 Option 3).
+ * Age-stale (or age+drift mixed) → --force bypasses TTL; drift-only → plain refetch.
+ */
+export function recoveryHintForStaleFailure(causes) {
+    if (causes.ageStale) {
+        return REMEDIATION_STALE_FORCE;
+    }
+    return REMEDIATION_STALE_PLAIN;
+}
+function formatDriftFailure(repo, drift) {
+    const parts = [];
+    if (drift.stateDriftNumbers.length > 0) {
+        parts.push(`${drift.stateDriftNumbers.length} cached-open issue(s) absent from live open set`);
+    }
+    if (drift.contentDriftNumbers.length > 0) {
+        parts.push(`${drift.contentDriftNumbers.length} TTL-fresh issue(s) with upstream content drift`);
+    }
+    return {
+        code: 1,
+        message: [
+            `❌ deft cache-fresh: stale-by-drift -- ${parts.join("; ")} (${repo}).`,
+            recoveryHintForStaleFailure({ ageStale: false, driftDetected: true }),
+        ].join("\n"),
+    };
+}
+function runDriftProbe(resolvedRepo, cacheRoot, source, options) {
+    if (options.probeDriftFn) {
+        return options.probeDriftFn(resolvedRepo, cacheRoot, source);
+    }
+    try {
+        return probeCacheDrift({ repo: resolvedRepo, source, cacheRoot });
+    }
+    catch {
+        return null;
+    }
+}
 const REMEDIATION_NO_CANDIDATES = [
     "  Recovery: run `deft triage:bootstrap` to initialise the triage log.",
 ].join("\n");
@@ -355,18 +398,18 @@ export function evaluate(projectRoot, options = {}) {
         allMetaPaths.length > 0 &&
         scopedMetaPaths.length === 0 &&
         candState === "populated";
-    // Step 5: Find newest entry
-    let maxFetchedAt = null;
-    let maxMetaPath = null;
+    // Step 5: Oldest in-scope entry age + drift probe (#1886)
+    let minFetchedAt = null;
+    let minMetaPath = null;
     for (const p of scopedMetaPaths.length > 0 ? scopedMetaPaths : allMetaPaths) {
         const ts = metaFetchedAt(p);
-        if (ts !== null && (maxFetchedAt === null || ts > maxFetchedAt)) {
-            maxFetchedAt = ts;
-            maxMetaPath = p;
+        if (ts !== null && (minFetchedAt === null || ts < minFetchedAt)) {
+            minFetchedAt = ts;
+            minMetaPath = p;
         }
     }
     const now = nowFn();
-    const ageMs = maxFetchedAt !== null ? now.getTime() - maxFetchedAt.getTime() : Infinity;
+    const ageMs = minFetchedAt !== null ? now.getTime() - minFetchedAt.getTime() : Infinity;
     const ageH = ageMs / (1000 * 3600);
     const stale = ageH > maxAgeHours;
     // Step 5b: --allow-stale bypass
@@ -383,15 +426,22 @@ export function evaluate(projectRoot, options = {}) {
         return { code: 0, message: warning };
     }
     if (stale) {
-        const display = maxMetaPath !== null ? relative(projectRoot, maxMetaPath) : "?";
+        const display = minMetaPath !== null ? relative(projectRoot, minMetaPath) : "?";
         return {
             code: 1,
             message: [
-                `❌ deft cache-fresh: cache is ${ageH.toFixed(1)}h old (max-age=${maxAgeHours}h); newest entry ${display}.`,
-                REMEDIATION_STALE,
+                `❌ deft cache-fresh: cache is ${ageH.toFixed(1)}h old (max-age=${maxAgeHours}h); oldest in-scope entry ${display}.`,
+                recoveryHintForStaleFailure({ ageStale: true, driftDetected: false }),
             ].join("\n"),
         };
     }
+    if (resolvedRepo !== null && !allowStale) {
+        const drift = runDriftProbe(resolvedRepo, cacheRoot, source, options);
+        if (drift !== null &&
+            (drift.stateDriftNumbers.length > 0 || drift.contentDriftNumbers.length > 0)) {
+            return formatDriftFailure(resolvedRepo, drift);
+        }
+    }
     // Step 6: --for-issue
     if (options.forIssue !== undefined && options.forIssue !== null) {
         const forResult = evaluateForIssue(resolvedRepo, options.forIssue, candidatesPath, cacheRoot, source, scopeRules, projectRoot);
@@ -416,7 +466,7 @@ export function evaluate(projectRoot, options = {}) {
         inScopeCount = scopedMetaPaths.length;
     }
     const repoLabel = resolvedRepo ?? "unknown-repo";
-    let msg = `✓ deft cache-fresh: ${repoLabel} -- ${inScopeCount} entry/ies in scope; newest fetched ${ageH.toFixed(1)}h ago (max-age=${maxAgeHours}h); ${statePhrase}.`;
+    let msg = `✓ deft cache-fresh: ${repoLabel} -- ${inScopeCount} entry/ies in scope; oldest fetched ${ageH.toFixed(1)}h ago (max-age=${maxAgeHours}h); ${statePhrase}.`;
     if (options.forIssue !== undefined && options.forIssue !== null) {
         msg += ` Issue #${options.forIssue} latest decision = accept; in subscription scope.`;
     }

package/dist/release-e2e/constants.d.ts

@@ -11,6 +11,8 @@ export declare const REHEARSAL_VERSION = "0.0.1";
  * .github/workflows/npm-publish.yml (types -> core -> content -> cli).
  */
 export declare const NPM_PUBLISH_PACKAGES: readonly ["types", "core", "content", "cli"];
+/** #1925: throwaway dist-tag so dry-run does not apply `latest` to 0.0.1. */
+export declare const NPM_E2E_REHEARSAL_TAG = "e2e-rehearsal";
 export declare const NPM_INSTALL_TIMEOUT_SECONDS = 600;
 export declare const NPM_BUILD_TIMEOUT_SECONDS = 600;
 export declare const NPM_PUBLISH_DRYRUN_TIMEOUT_SECONDS = 180;

package/dist/release-e2e/constants.js

@@ -11,6 +11,8 @@ export const REHEARSAL_VERSION = "0.0.1";
  * .github/workflows/npm-publish.yml (types -> core -> content -> cli).
  */
 export const NPM_PUBLISH_PACKAGES = ["types", "core", "content", "cli"];
+/** #1925: throwaway dist-tag so dry-run does not apply `latest` to 0.0.1. */
+export const NPM_E2E_REHEARSAL_TAG = "e2e-rehearsal";
 export const NPM_INSTALL_TIMEOUT_SECONDS = 600;
 export const NPM_BUILD_TIMEOUT_SECONDS = 600;
 export const NPM_PUBLISH_DRYRUN_TIMEOUT_SECONDS = 180;

package/dist/release-e2e/flags.js

@@ -25,6 +25,7 @@ export function parseE2EFlags(argv) {
     let keepRepo = false;
     let projectRoot = null;
     let skipNpm = false;
+    let legacyBridge = false;
     const unknown = [];
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -42,6 +43,9 @@ export function parseE2EFlags(argv) {
         else if (arg === "--skip-npm") {
             skipNpm = true;
         }
+        else if (arg === "--legacy-bridge") {
+            legacyBridge = true;
+        }
         else if (arg === "--owner") {
             const next = argv[i + 1];
             if (next === undefined || next.startsWith("-")) {
@@ -75,6 +79,6 @@ export function parseE2EFlags(argv) {
             unknown.push(arg);
         }
     }
-    return { help, owner, dryRun, keepRepo, projectRoot, skipNpm, unknown };
+    return { help, owner, dryRun, keepRepo, projectRoot, skipNpm, legacyBridge, unknown };
 }
 //# sourceMappingURL=flags.js.map

package/dist/release-e2e/legacy-bridge-leg.d.ts

@@ -0,0 +1,134 @@
+import { type LegacyLayoutKind } from "../init-deposit/legacy-detect.js";
+import { type InstallManifestFields } from "../init-deposit/scaffold.js";
+import type { E2ESeams } from "./types.js";
+/** The frozen Go bridge repo (the published release lives under deftai/directive). */
+export declare const GO_BRIDGE_REPO = "deftai/directive";
+/** A legacy on-disk shape the stage-1 bridge migrates and the npm CLI refuses. */
+export interface LegacyFixtureSpec {
+    readonly kind: LegacyLayoutKind;
+    readonly provision: (dir: string) => void;
+}
+/**
+ * The legacy layouts the leg provisions + asserts. Covers the four shapes the
+ * detector recognises (legacy-detect.ts): orphan `.deft/VERSION`, legacy
+ * `deft/`-prefixed root, git-clone / submodule, and a pre-v0.27 sentinel-only
+ * AGENTS.md. Each fixture lands in its own clean throwaway dir.
+ */
+export declare const LEGACY_FIXTURES: readonly LegacyFixtureSpec[];
+/** Provision the named legacy fixture under `dir`. */
+export declare function provisionLegacyFixture(dir: string, kind: LegacyLayoutKind): void;
+/**
+ * Stage-0 fixture-shape assertions: every legacy fixture is classified as legacy
+ * with its expected kind, and the npm refuse-preflight surface (story P) would
+ * refuse it (we exercise the version-neutral two-step refusal message). This is
+ * the boundary that makes the two-stage migration load-bearing: the npm path
+ * NEVER migrates a legacy layout -- the frozen Go bridge does (stage 1) first.
+ */
+export declare function assertLegacyFixturesDetectedAndRefused(workRoot: string): [boolean, string];
+/**
+ * The canonical installer manifest fields the frozen Go bridge writes into
+ * `.deft/core/VERSION`. Field names + order come from the installer's
+ * `buildInstallManifestText` (the TS port of the Go `BuildInstallManifestText`),
+ * so this fixture is the same shape a real frozen-bridge run deposits.
+ */
+export declare const CANONICAL_INSTALLER_MANIFEST_FIELDS: InstallManifestFields;
+/**
+ * The install-manifest field keys a canonical installer VERSION carries, derived
+ * from the installer's own `buildInstallManifestText` output so the handshake
+ * expectation tracks the real installer field shape rather than restating it.
+ * `directive migrate` consumes this VERSION; a drift away from these keys is the
+ * handshake break this leg now asserts against.
+ */
+export declare function installerManifestFieldKeys(): string[];
+/**
+ * Assert an installer-shaped VERSION is migrate-acceptable: `parseInstallManifest`
+ * accepts it AND it carries every canonical installer manifest field
+ * ({@link installerManifestFieldKeys}) with a non-empty value. A drifted field
+ * shape (missing or renamed key, empty value) returns a handshake mismatch
+ * reason so the leg fails loudly rather than letting `directive migrate` stamp a
+ * non-installer VERSION npm-managed. This is the stage-2 handshake the #1912
+ * freeze hinges on (the installer VERSION the npm CLI accepts as canonical-ready).
+ */
+export declare function assertInstallerVersionMigrateAcceptable(versionText: string): [boolean, string];
+/**
+ * Provision a canonical-vendored `.deft/core` deposit -- the shape the stage-1
+ * bridge produces from a legacy layout. Writes an installer-shaped VERSION (via
+ * the installer's own `writeInstallManifest`) unless `versionTextOverride` is
+ * supplied, in which case the raw override text is written verbatim so a test can
+ * drive a drifted VERSION through the stage-2 handshake. Optionally renders
+ * AGENTS.md when the agents-entry template is available (so the npm-hybrid
+ * end-state check can assert the managed-section the way `directive init`/`update`
+ * do). Returns the VERSION manifest path so the caller can assert the handshake.
+ */
+export declare function provisionCanonicalVendoredDeposit(projectDir: string, agentsTemplatePath: string | null, versionTextOverride?: string | null): {
+    deftDir: string;
+    agentsRendered: boolean;
+    manifestPath: string;
+};
+/**
+ * Stage-2 assertion: drive a canonical-vendored deposit through `directive
+ * migrate` (and the init/update AGENTS.md render) to a valid npm-hybrid deposit.
+ * Asserts migrate stamps the deposit npm-managed, is idempotent (already-hybrid
+ * on the second run), and leaves a `managed_by: 'npm'` manifest.
+ */
+export declare function assertNpmHybridMigration(workRoot: string, agentsTemplatePath: string | null, seams?: LegacyBridgeLegSeams): [boolean, string];
+/** The outcome of resolving which downloaded asset is the bridge binary for this host. */
+export type BridgeAssetSelection = {
+    kind: "ok";
+    name: string;
+} | {
+    kind: "none";
+} | {
+    kind: "no-platform-match";
+    candidates: string[];
+};
+/**
+ * Pick the deft-install bridge binary matching the current host platform/arch.
+ *
+ * Go releases publish one asset per OS/arch (e.g. `deft-install-linux-amd64`,
+ * `deft-install-darwin-arm64`, `deft-install-windows-amd64.exe`). Selecting
+ * `assets[0]` alphabetically silently picks the wrong binary on a multi-asset
+ * release (darwin sorts before linux), producing an exec-format failure on a
+ * non-Darwin runner. This resolves the host-matching asset instead and reports
+ * a precise outcome when none matches:
+ *   - single deft-install asset -> use it (single-binary releases, back-compat);
+ *   - prefer an asset whose name carries BOTH the GOOS and GOARCH tokens;
+ *   - else fall back to a GOOS-only match (releases that omit the arch suffix);
+ *   - else `no-platform-match` so the caller fails loudly rather than guessing.
+ */
+export declare function selectBridgeAsset(fileNames: readonly string[], platform?: NodeJS.Platform, arch?: string): BridgeAssetSelection;
+/**
+ * The frozen-mode real handoff (reached ONLY once the operator pins the SoT):
+ * download the frozen Go bridge binary at the pinned tag and run it against a
+ * legacy fixture to normalise it to canonical-vendored. Soft-skips when `gh` is
+ * absent. Never builds/cuts a release -- it consumes an already-published one.
+ */
+export declare function downloadAndRunFrozenBridge(pin: string, fixtureDir: string, seams?: E2ESeams & LegacyBridgeLegSeams): [boolean, string];
+export interface LegacyBridgeLegSeams {
+    /** Test seam: override the Tier-0 SoT reader (default: real lastGoInstaller). */
+    lastGoInstaller?: () => string | null;
+    /** Test seam: engine-resolve check used by the stage-2 migrate (default: npm present). */
+    resolveEngine?: () => string | null;
+    /** Test seam: deterministic ISO timestamp for the migrate backup filename. */
+    nowIso?: () => string;
+    /** Test seam: override the frozen-mode bridge handoff (default: gh release download + run). */
+    runFrozenBridge?: (pin: string, fixtureDir: string) => [boolean, string];
+    /** Override the agents-entry template path (default: <projectRoot>/content/templates/agents-entry.md). */
+    agentsTemplatePath?: string | null;
+    /**
+     * Test seam: write this raw text to the stage-2 `.deft/core/VERSION` instead of
+     * the installer-shaped manifest, to drive a drifted VERSION through the
+     * migrate-acceptable handshake assertion (default: installer-shaped manifest).
+     */
+    versionTextOverride?: string;
+}
+/**
+ * Run the pinned legacy -> bridge -> npm-hybrid migration leg.
+ *
+ * Returns `[ok, reason]` like the other release-e2e legs. Soft-skips (ok=true)
+ * when npm is absent. While the SoT is null (pending-pin) it asserts the
+ * fixture-shape + stage-2 npm-hybrid checks and SKIPS the real frozen-binary
+ * download; once the SoT is pinned it additionally runs the real bridge handoff.
+ */
+export declare function runLegacyBridgeLeg(projectRoot: string, seams?: E2ESeams & LegacyBridgeLegSeams): [boolean, string];
+//# sourceMappingURL=legacy-bridge-leg.d.ts.map