@deftai/directive-core 0.55.0

package/dist/release/flags.js

@@ -0,0 +1,131 @@
+import { DEFAULT_BASE_BRANCH, RELEASE_HELP } from "./constants.js";
+export function parseReleaseFlags(args) {
+    let help = false;
+    let dryRun = false;
+    let skipTag = false;
+    let skipRelease = false;
+    let allowDirty = false;
+    let allowVbriefDrift = false;
+    let skipCi = false;
+    let skipBuild = false;
+    let draft = true;
+    let repo = null;
+    let baseBranch = DEFAULT_BASE_BRANCH;
+    let projectRoot = null;
+    let summary = null;
+    let version = null;
+    const unknown = [];
+    const takeValue = (flag, i) => {
+        if (i + 1 >= args.length) {
+            unknown.push(`${flag} (missing value)`);
+            return null;
+        }
+        return args[i + 1] ?? null;
+    };
+    let i = 0;
+    while (i < args.length) {
+        const token = args[i] ?? "";
+        if (token === "-h" || token === "--help") {
+            help = true;
+        }
+        else if (token === "--dry-run") {
+            dryRun = true;
+        }
+        else if (token === "--skip-tag") {
+            skipTag = true;
+        }
+        else if (token === "--skip-release") {
+            skipRelease = true;
+        }
+        else if (token === "--allow-dirty") {
+            allowDirty = true;
+        }
+        else if (token === "--allow-vbrief-drift") {
+            allowVbriefDrift = true;
+        }
+        else if (token === "--skip-ci") {
+            skipCi = true;
+        }
+        else if (token === "--skip-build") {
+            skipBuild = true;
+        }
+        else if (token === "--no-draft") {
+            draft = false;
+        }
+        else if (token === "--repo") {
+            repo = takeValue(token, i);
+            if (repo !== null)
+                i += 1;
+        }
+        else if (token.startsWith("--repo=")) {
+            repo = token.slice("--repo=".length) || null;
+            if (!repo)
+                unknown.push("--repo= (empty value)");
+        }
+        else if (token === "--base-branch") {
+            const v = takeValue(token, i);
+            if (v !== null) {
+                baseBranch = v;
+                i += 1;
+            }
+        }
+        else if (token.startsWith("--base-branch=")) {
+            const v = token.slice("--base-branch=".length);
+            if (v)
+                baseBranch = v;
+            else
+                unknown.push("--base-branch= (empty value)");
+        }
+        else if (token === "--project-root") {
+            projectRoot = takeValue(token, i);
+            if (projectRoot !== null)
+                i += 1;
+        }
+        else if (token.startsWith("--project-root=")) {
+            projectRoot = token.slice("--project-root=".length) || null;
+            if (!projectRoot)
+                unknown.push("--project-root= (empty value)");
+        }
+        else if (token === "--summary") {
+            summary = takeValue(token, i);
+            if (summary !== null)
+                i += 1;
+        }
+        else if (token.startsWith("--summary=")) {
+            summary = token.slice("--summary=".length) || null;
+            if (!summary)
+                unknown.push("--summary= (empty value)");
+        }
+        else if (token.startsWith("-")) {
+            unknown.push(token);
+        }
+        else if (version === null) {
+            version = token;
+        }
+        else {
+            unknown.push(token);
+        }
+        i += 1;
+    }
+    return {
+        help,
+        version,
+        repo,
+        baseBranch,
+        projectRoot,
+        dryRun,
+        skipTag,
+        skipRelease,
+        allowDirty,
+        allowVbriefDrift,
+        skipCi,
+        skipBuild,
+        draft,
+        summary,
+        unknown,
+    };
+}
+export function formatReleaseHelp() {
+    return RELEASE_HELP;
+}
+//# sourceMappingURL=flags.js.map

package/dist/release/gh.d.ts

@@ -0,0 +1,16 @@
+import type { ReleaseSeams } from "./types.js";
+export declare function resolveGh(seams?: ReleaseSeams): string | null;
+export declare function checkTagAvailable(version: string, repo: string, projectRoot: string, seams?: ReleaseSeams): [boolean, string];
+export declare function createGithubRelease(projectRoot: string, version: string, repo: string, notes: string, options?: {
+    draft?: boolean;
+    prerelease?: boolean;
+}, seams?: ReleaseSeams): [boolean, string];
+export declare function verifyReleaseDraft(projectRoot: string, version: string, repo: string, options?: {
+    maxAttempts?: number;
+    interval?: number;
+    sleep?: (seconds: number) => void;
+}, seams?: ReleaseSeams): [boolean, string];
+/** Read upgrade banner for prependUpgradeBanner seam. */
+export declare function readTextFile(path: string): string | null;
+export declare function defaultMkdtemp(): string;
+//# sourceMappingURL=gh.d.ts.map

package/dist/release/gh.js

@@ -0,0 +1,210 @@
+import { existsSync, mkdtempSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runGit } from "./git.js";
+import { defaultWhich, spawnText } from "./spawn.js";
+export function resolveGh(seams = {}) {
+    const which = seams.whichGh ?? defaultWhich;
+    return which("gh");
+}
+export function checkTagAvailable(version, repo, projectRoot, seams = {}) {
+    const tag = `v${version}`;
+    const local = runGit(projectRoot, ["tag", "-l", tag], seams);
+    if (local.status !== 0) {
+        return [false, `git tag -l failed: ${local.stderr.trim()}`];
+    }
+    if (local.stdout.trim() === tag) {
+        return [
+            false,
+            `local tag ${tag} already exists; choose a different version ` +
+                "(operator typo of a prior release is the most likely cause)",
+        ];
+    }
+    const remote = runGit(projectRoot, ["ls-remote", "--tags", "origin", `refs/tags/${tag}`], seams);
+    let remoteUnverifiedNote = "";
+    if (remote.status !== 0) {
+        const stderr = remote.stderr.trim();
+        const firstLine = stderr.split("\n")[0] ?? "no stderr";
+        remoteUnverifiedNote = ` (remote UNVERIFIED -- git ls-remote failed: ${firstLine})`;
+    }
+    else if (remote.stdout.includes(`refs/tags/${tag}`)) {
+        return [false, `remote tag ${tag} already exists on origin; choose a different version`];
+    }
+    const ghPath = resolveGh(seams);
+    if (ghPath === null) {
+        return [
+            true,
+            `local clean${remoteUnverifiedNote} (gh CLI not on PATH; ` +
+                "GitHub release surface UNVERIFIED -- install gh or pass " +
+                "--skip-release to suppress this caveat)",
+        ];
+    }
+    const spawn = seams.spawnText ?? spawnText;
+    const gh = spawn(ghPath, ["release", "view", tag, "--repo", repo, "--json", "tagName"], {
+        cwd: projectRoot,
+        timeoutMs: 30_000,
+    });
+    if (gh.status === 0) {
+        return [false, `GitHub release ${tag} already exists on ${repo}; choose a different version`];
+    }
+    return [true, `local clean${remoteUnverifiedNote}; no GitHub release ${tag} on ${repo}`];
+}
+export function createGithubRelease(projectRoot, version, repo, notes, options = {}, seams = {}) {
+    const draft = options.draft ?? true;
+    const prerelease = options.prerelease ?? false;
+    const ghPath = resolveGh(seams);
+    if (ghPath === null) {
+        return [false, "gh CLI not found on PATH"];
+    }
+    const tag = `v${version}`;
+    const cmd = [ghPath, "release", "create", tag, "--repo", repo, "--title", tag];
+    if (draft)
+        cmd.push("--draft");
+    if (prerelease)
+        cmd.push("--prerelease");
+    let notesFile = null;
+    if (notes) {
+        const dir = tmpdir();
+        notesFile = join(dir, `deft-release-notes-${process.pid}-${Date.now()}.md`);
+        writeFileSync(notesFile, notes, { encoding: "utf8" });
+        cmd.push("--notes-file", notesFile);
+    }
+    else {
+        cmd.push("--generate-notes");
+    }
+    const spawn = seams.spawnText ?? spawnText;
+    try {
+        const result = spawn(ghPath, cmd.slice(1), {
+            cwd: projectRoot,
+            timeoutMs: 120_000,
+            env: { ...process.env },
+        });
+        if (result.status !== 0) {
+            return [false, `gh release create failed: ${result.stderr.trim()}`];
+        }
+        const flags = [];
+        if (draft)
+            flags.push("draft");
+        if (prerelease)
+            flags.push("prerelease");
+        const suffix = flags.length > 0 ? ` (${flags.join(", ")})` : "";
+        return [true, `created GitHub release ${tag}${suffix}`];
+    }
+    finally {
+        if (notesFile !== null) {
+            try {
+                unlinkSync(notesFile);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+    }
+}
+function ghReleaseViewIsDraft(ghPath, version, repo, projectRoot, seams) {
+    const tag = `v${version}`;
+    const spawn = seams.spawnText ?? spawnText;
+    const result = spawn(ghPath, ["release", "view", tag, "--repo", repo, "--json", "isDraft"], {
+        cwd: projectRoot,
+        timeoutMs: 30_000,
+        env: { ...process.env },
+    });
+    if (result.status !== 0) {
+        const stderr = result.stderr.trim();
+        const lower = stderr.toLowerCase();
+        if (lower.includes("not found") || lower.includes("release not found")) {
+            return ["not-found", stderr];
+        }
+        return ["error", stderr];
+    }
+    try {
+        const payload = JSON.parse(result.stdout || "{}");
+        if (payload.isDraft === true)
+            return ["draft", ""];
+        if (payload.isDraft === false)
+            return ["public", ""];
+        return ["error", `isDraft missing from gh response: ${JSON.stringify(payload)}`];
+    }
+    catch (exc) {
+        return ["error", `unparseable gh JSON: ${String(exc)}`];
+    }
+}
+function ghReleaseFlipToDraft(ghPath, version, repo, projectRoot, seams) {
+    const tag = `v${version}`;
+    const spawn = seams.spawnText ?? spawnText;
+    const result = spawn(ghPath, ["release", "edit", tag, "--repo", repo, "--draft=true"], {
+        cwd: projectRoot,
+        timeoutMs: 30_000,
+        env: { ...process.env },
+    });
+    if (result.status !== 0) {
+        return [false, `gh release edit failed: ${result.stderr.trim()}`];
+    }
+    return [true, `flipped ${tag} to draft`];
+}
+export function verifyReleaseDraft(projectRoot, version, repo, options = {}, seams = {}) {
+    const maxAttempts = options.maxAttempts ?? 5;
+    const interval = options.interval ?? 1.0;
+    const sleepFn = options.sleep ??
+        seams.sleep ??
+        ((s) => {
+            const start = Date.now();
+            while (Date.now() - start < s * 1000) {
+                // busy-wait fallback for tests injecting sleep
+            }
+        });
+    if (maxAttempts <= 0) {
+        return [true, "verify gate disabled (max_attempts <= 0)"];
+    }
+    const ghPath = resolveGh(seams);
+    if (ghPath === null) {
+        process.stderr.write("WARNING: cannot verify draft state (gh CLI not found on PATH); " +
+            "defense-in-depth gate skipped (see #724)\n");
+        return [true, "gh CLI not found on PATH; verify gate skipped"];
+    }
+    let lastState = "";
+    let lastDetail = "";
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        const [state, detail] = ghReleaseViewIsDraft(ghPath, version, repo, projectRoot, seams);
+        lastState = state;
+        lastDetail = detail;
+        if (state === "draft") {
+            return [true, `verified draft on attempt ${attempt}/${maxAttempts}`];
+        }
+        if (state === "public") {
+            process.stderr.write(`WARNING: release v${version} landed as public; ` +
+                "flipping to draft (defense-in-depth, see #724)\n");
+            const [ok, reason] = ghReleaseFlipToDraft(ghPath, version, repo, projectRoot, seams);
+            if (ok)
+                return [true, `flipped to draft (${reason})`];
+            return [false, reason];
+        }
+        if (attempt < maxAttempts) {
+            sleepFn(interval);
+        }
+    }
+    if (lastState === "not-found") {
+        process.stderr.write(`WARNING: release v${version} not found within ` +
+            `${maxAttempts}*${interval}s budget; release.yml CI may still ` +
+            "be processing (see #724)\n");
+        return [true, "not found within budget; verify gate inconclusive"];
+    }
+    process.stderr.write(`WARNING: verify gate could not confirm draft state for v${version}: ` +
+        `last state '${lastState}'; detail: ${lastDetail} (see #724)\n`);
+    return [true, `inconclusive (${lastState}); verify gate skipped`];
+}
+/** Read upgrade banner for prependUpgradeBanner seam. */
+export function readTextFile(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function defaultMkdtemp() {
+    return mkdtempSync(join(tmpdir(), "deft-release-"));
+}
+//# sourceMappingURL=gh.js.map

package/dist/release/git.d.ts

@@ -0,0 +1,11 @@
+import { spawnText } from "./spawn.js";
+import type { ReleaseSeams } from "./types.js";
+export declare function releaseSubprocessEnv(base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function runGit(projectRoot: string, args: readonly string[], seams?: ReleaseSeams, env?: NodeJS.ProcessEnv): ReturnType<typeof spawnText>;
+export declare function checkGitClean(projectRoot: string, seams?: ReleaseSeams): [boolean, string];
+export declare function currentBranch(projectRoot: string, seams?: ReleaseSeams): string;
+export declare function releaseCommitSubject(version: string): string;
+export declare function commitReleaseArtifacts(projectRoot: string, version: string, seams?: ReleaseSeams): [boolean, string];
+export declare function createTag(projectRoot: string, version: string, seams?: ReleaseSeams): [boolean, string];
+export declare function pushRelease(projectRoot: string, version: string, baseBranch: string, seams?: ReleaseSeams): [boolean, string];
+//# sourceMappingURL=git.d.ts.map

package/dist/release/git.js

@@ -0,0 +1,84 @@
+import { existsSync, statSync } from "node:fs";
+import { BRANCH_GATE_BYPASS_ENV, DESTRUCTIVE_GH_GATE_BYPASS_ENV, RELEASE_ARTIFACTS, } from "./constants.js";
+import { spawnText } from "./spawn.js";
+export function releaseSubprocessEnv(base = process.env) {
+    return {
+        ...base,
+        [BRANCH_GATE_BYPASS_ENV]: "1",
+        [DESTRUCTIVE_GH_GATE_BYPASS_ENV]: "1",
+    };
+}
+export function runGit(projectRoot, args, seams = {}, env) {
+    const spawn = seams.spawnText ?? spawnText;
+    return spawn("git", ["-C", projectRoot, ...args], {
+        env,
+        timeoutMs: 30_000,
+    });
+}
+export function checkGitClean(projectRoot, seams = {}) {
+    const result = runGit(projectRoot, ["status", "--porcelain"], seams);
+    if (result.status !== 0) {
+        return [false, `git status failed: ${result.stderr.trim()}`];
+    }
+    const output = result.stdout.trim();
+    if (output) {
+        return [false, output];
+    }
+    return [true, ""];
+}
+export function currentBranch(projectRoot, seams = {}) {
+    const result = runGit(projectRoot, ["branch", "--show-current"], seams);
+    if (result.status !== 0) {
+        return "";
+    }
+    return result.stdout.trim();
+}
+export function releaseCommitSubject(version) {
+    return `chore(release): v${version} -- promote CHANGELOG + ROADMAP`;
+}
+export function commitReleaseArtifacts(projectRoot, version, seams = {}) {
+    const exists = seams.fileExists ??
+        ((p) => {
+            try {
+                return existsSync(p) && statSync(p).isFile();
+            }
+            catch {
+                return false;
+            }
+        });
+    const pathsToStage = RELEASE_ARTIFACTS.filter((rel) => exists(`${projectRoot}/${rel}`));
+    if (pathsToStage.length === 0) {
+        return [true, "no release artifacts to commit (none exist)"];
+    }
+    const add = runGit(projectRoot, ["add", "--", ...pathsToStage], seams);
+    if (add.status !== 0) {
+        return [false, `git add failed: ${add.stderr.trim()}`];
+    }
+    const diff = runGit(projectRoot, ["diff", "--cached", "--quiet"], seams);
+    if (diff.status === 0) {
+        return [true, "release artifacts already up-to-date; no commit needed"];
+    }
+    const subject = releaseCommitSubject(version);
+    const commit = runGit(projectRoot, ["commit", "-m", subject], seams, releaseSubprocessEnv());
+    if (commit.status !== 0) {
+        return [false, `git commit failed: ${commit.stderr.trim()}`];
+    }
+    return [true, `committed release artifacts (${subject})`];
+}
+export function createTag(projectRoot, version, seams = {}) {
+    const tag = `v${version}`;
+    const result = runGit(projectRoot, ["tag", "-a", tag, "-m", `Release ${tag}`], seams, releaseSubprocessEnv());
+    if (result.status !== 0) {
+        return [false, `git tag failed: ${result.stderr.trim()}`];
+    }
+    return [true, `created tag ${tag}`];
+}
+export function pushRelease(projectRoot, version, baseBranch, seams = {}) {
+    const tag = `v${version}`;
+    const result = runGit(projectRoot, ["push", "--atomic", "origin", baseBranch, tag], seams, releaseSubprocessEnv());
+    if (result.status !== 0) {
+        return [false, `git push failed: ${result.stderr.trim()}`];
+    }
+    return [true, `pushed ${baseBranch} + ${tag} to origin`];
+}
+//# sourceMappingURL=git.js.map

package/dist/release/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./constants.js";
+export * from "./flags.js";
+export * from "./gh.js";
+export * from "./git.js";
+export * from "./main.js";
+export * from "./paths.js";
+export * from "./pipeline.js";
+export * from "./pyproject.js";
+export * from "./pyproject-sync.js";
+export * from "./python-bridge.js";
+export * from "./spawn.js";
+export * from "./types.js";
+export * from "./version.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/release/index.js

@@ -0,0 +1,15 @@
+/* v8 ignore file -- re-export barrel; covered via main.ts */
+export * from "./constants.js";
+export * from "./flags.js";
+export * from "./gh.js";
+export * from "./git.js";
+export * from "./main.js";
+export * from "./paths.js";
+export * from "./pipeline.js";
+export * from "./pyproject.js";
+export * from "./pyproject-sync.js";
+export * from "./python-bridge.js";
+export * from "./spawn.js";
+export * from "./types.js";
+export * from "./version.js";
+//# sourceMappingURL=index.js.map

package/dist/release/main.d.ts

@@ -0,0 +1,3 @@
+import type { ReleaseSeams } from "./types.js";
+export declare function cmdRelease(args: readonly string[], seams?: ReleaseSeams): number;
+//# sourceMappingURL=main.d.ts.map

package/dist/release/main.js

@@ -0,0 +1,47 @@
+import { EXIT_CONFIG_ERROR } from "./constants.js";
+import { formatReleaseHelp, parseReleaseFlags } from "./flags.js";
+import { resolveProjectRoot, resolveRepo } from "./paths.js";
+import { runPipeline } from "./pipeline.js";
+import { validateVersion } from "./version.js";
+export function cmdRelease(args, seams = {}) {
+    const flags = parseReleaseFlags(args);
+    if (flags.help) {
+        process.stdout.write(formatReleaseHelp());
+        return 0;
+    }
+    if (flags.unknown.length > 0) {
+        process.stderr.write(`release: error: unrecognized arguments: ${flags.unknown.join(" ")}\n`);
+        return EXIT_CONFIG_ERROR;
+    }
+    if (flags.version === null) {
+        process.stderr.write("release: error: the following arguments are required: version\n");
+        return EXIT_CONFIG_ERROR;
+    }
+    try {
+        validateVersion(flags.version);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Error: ${msg}\n`);
+        return EXIT_CONFIG_ERROR;
+    }
+    const projectRoot = resolveProjectRoot(flags.projectRoot);
+    const repo = resolveRepo(flags.repo, projectRoot, seams);
+    const config = {
+        version: flags.version,
+        repo,
+        baseBranch: flags.baseBranch,
+        projectRoot,
+        dryRun: flags.dryRun,
+        skipTag: flags.skipTag,
+        skipRelease: flags.skipRelease,
+        allowDirty: flags.allowDirty,
+        draft: flags.draft,
+        skipCi: flags.skipCi,
+        skipBuild: flags.skipBuild,
+        summary: flags.summary,
+        allowVbriefDrift: flags.allowVbriefDrift,
+    };
+    return runPipeline(config, seams);
+}
+//# sourceMappingURL=main.js.map

package/dist/release/paths.d.ts

@@ -0,0 +1,6 @@
+import type { ReleaseSeams } from "./types.js";
+export declare function resolveProjectRoot(argRoot: string | null): string;
+export declare function resolveRepo(argRepo: string | null, projectRoot: string, seams?: Pick<ReleaseSeams, "spawnText">): string;
+export declare function resolveScriptsDir(frameworkRoot?: string): string;
+export declare function todayIso(now?: () => Date): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/release/paths.js

@@ -0,0 +1,39 @@
+import { resolve } from "node:path";
+import { resolveDefaultFrameworkRoot, resolveScriptDir } from "../doctor/paths.js";
+import { DEFAULT_REPO } from "./constants.js";
+import { spawnText } from "./spawn.js";
+export function resolveProjectRoot(argRoot) {
+    if (argRoot !== null) {
+        return resolve(argRoot);
+    }
+    const envRoot = process.env.DEFT_PROJECT_ROOT?.trim();
+    if (envRoot) {
+        return resolve(envRoot);
+    }
+    return resolveDefaultFrameworkRoot();
+}
+export function resolveRepo(argRepo, projectRoot, seams = {}) {
+    if (argRepo) {
+        return argRepo;
+    }
+    const spawn = seams.spawnText ?? spawnText;
+    const result = spawn("git", ["-C", projectRoot, "remote", "get-url", "origin"], {
+        timeoutMs: 10_000,
+    });
+    if (result.status !== 0) {
+        return DEFAULT_REPO;
+    }
+    const url = result.stdout.trim();
+    const match = /^(?:https?:\/\/github\.com\/|git@github\.com:)(?<owner>[^/]+)\/(?<repo>[^/]+?)(?:\.git)?$/.exec(url);
+    if (!match?.groups) {
+        return DEFAULT_REPO;
+    }
+    return `${match.groups.owner}/${match.groups.repo}`;
+}
+export function resolveScriptsDir(frameworkRoot) {
+    return resolveScriptDir(frameworkRoot);
+}
+export function todayIso(now = () => new Date()) {
+    return now().toISOString().slice(0, 10);
+}
+//# sourceMappingURL=paths.js.map

package/dist/release/pipeline.d.ts

@@ -0,0 +1,6 @@
+import type { ReleaseConfig, ReleaseSeams } from "./types.js";
+export declare function emit(step: number, label: string, status: string, target?: NodeJS.WriteStream & {
+    fd: 2;
+}): void;
+export declare function runPipeline(config: ReleaseConfig, seams?: ReleaseSeams): number;
+//# sourceMappingURL=pipeline.d.ts.map