@deftai/directive-core 0.55.0

package/dist/render/spec-render.js

@@ -0,0 +1,362 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { LIFECYCLE_BUCKETS, RENDERABLE_SPEC_STATUSES, SCOPE_SUMMARY_NARRATIVES, SPEC_RENDER_BANNER, SPECIFICATION_NARRATIVE_KEY_ORDER, } from "./constants.js";
+import { validateSpec } from "./spec-validate.js";
+function readEdgeEndpoints(edge) {
+    if (typeof edge !== "object" || edge === null || Array.isArray(edge))
+        return ["", ""];
+    const e = edge;
+    const frm = String(e.from ?? e.source ?? "") || "";
+    const to = String(e.to ?? e.target ?? "") || "";
+    return [frm, to];
+}
+function loadScopeVbriefs(folder) {
+    if (!existsSync(folder))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(folder)
+            .filter((n) => n.endsWith(".vbrief.json"))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries) {
+        const path = join(folder, name);
+        try {
+            const data = JSON.parse(readFileSync(path, "utf8"));
+            let stem = name;
+            if (stem.endsWith(".vbrief.json"))
+                stem = stem.slice(0, -".vbrief.json".length);
+            out.push([stem, data]);
+        }
+        catch {
+            /* skip malformed */
+        }
+    }
+    return out;
+}
+function scopeId(stem, vbrief) {
+    const plan = vbrief.plan;
+    if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
+        const planId = plan.id;
+        if (typeof planId === "string" && planId)
+            return planId;
+    }
+    return stem;
+}
+function crossScopeDepMap(scopes) {
+    const scopeIds = new Set(scopes.map(([stem, vb]) => scopeId(stem, vb)));
+    const depMap = {};
+    for (const [, vbrief] of scopes) {
+        const plan = vbrief.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan))
+            continue;
+        const edges = plan.edges;
+        if (!Array.isArray(edges))
+            continue;
+        for (const edge of edges) {
+            const [frm, to] = readEdgeEndpoints(edge);
+            if (frm && to && scopeIds.has(frm) && scopeIds.has(to)) {
+                if (!depMap[to])
+                    depMap[to] = [];
+                depMap[to].push(frm);
+            }
+        }
+    }
+    return depMap;
+}
+function topoSortScopes(scopes, depMap) {
+    if (scopes.length === 0)
+        return [];
+    const idByIndex = scopes.map(([stem, vb]) => scopeId(stem, vb));
+    const idToIndex = new Map(idByIndex.map((sid, i) => [sid, i]));
+    const depths = {};
+    const depth = (sid, visited = null) => {
+        if (sid in depths)
+            return depths[sid] ?? 0;
+        const vis = visited ?? new Set();
+        if (vis.has(sid))
+            return 0;
+        vis.add(sid);
+        const deps = (depMap[sid] ?? []).filter((d) => idToIndex.has(d));
+        if (deps.length === 0) {
+            depths[sid] = 0;
+            return 0;
+        }
+        const result = Math.max(...deps.map((d) => depth(d, vis))) + 1;
+        depths[sid] = result;
+        return result;
+    };
+    for (const sid of idByIndex)
+        depth(sid);
+    const orderedIndices = [...idByIndex.keys()].sort((a, b) => (depths[idByIndex[a] ?? ""] ?? 0) - (depths[idByIndex[b] ?? ""] ?? 0) || a - b);
+    return orderedIndices.map((i) => scopes[i]);
+}
+function scopeSummaryNarrative(plan) {
+    const narratives = plan.narratives;
+    if (typeof narratives !== "object" || narratives === null || Array.isArray(narratives)) {
+        return "";
+    }
+    const narr = narratives;
+    for (const key of SCOPE_SUMMARY_NARRATIVES) {
+        const val = narr[key];
+        if (typeof val === "string" && val.trim())
+            return val.trim();
+    }
+    for (const val of Object.values(narr)) {
+        if (typeof val === "string" && val.trim())
+            return val.trim();
+    }
+    return "";
+}
+function splitAcceptance(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => String(item).trim()).filter((s) => s.length > 0);
+    }
+    if (typeof value !== "string")
+        return [];
+    const parts = [];
+    for (const line of value.split("\n")) {
+        let cleaned = line.trim();
+        if (!cleaned)
+            continue;
+        if (cleaned.startsWith("- ") || cleaned.startsWith("* ")) {
+            cleaned = cleaned.slice(2).trim();
+        }
+        if (cleaned)
+            parts.push(cleaned);
+    }
+    return parts;
+}
+function itemAcceptance(item) {
+    const narrative = item.narrative;
+    if (typeof narrative !== "object" || narrative === null || Array.isArray(narrative))
+        return [];
+    return splitAcceptance(narrative.Acceptance);
+}
+function renderScopeBlock(stem, vbrief) {
+    const plan = vbrief.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan))
+        return [];
+    const planObj = plan;
+    const title = String(planObj.title ?? stem);
+    const status = String(planObj.status ?? "");
+    let heading = `### ${stem}: ${title}`;
+    if (status)
+        heading += `  \`[${status}]\``;
+    const lines = [`${heading}\n`];
+    const summary = scopeSummaryNarrative(planObj);
+    if (summary)
+        lines.push(`${summary}\n`);
+    const narratives = planObj.narratives;
+    if (typeof narratives === "object" && narratives !== null && !Array.isArray(narratives)) {
+        const scopeAcceptance = splitAcceptance(narratives.Acceptance);
+        if (scopeAcceptance.length > 0) {
+            lines.push("**Scope Acceptance**:\n");
+            for (const criterion of scopeAcceptance)
+                lines.push(`- ${criterion}`);
+            lines.push("");
+        }
+    }
+    const items = planObj.items;
+    if (Array.isArray(items) && items.length > 0) {
+        lines.push("**Acceptance**:\n");
+        for (const item of items) {
+            if (typeof item !== "object" || item === null || Array.isArray(item))
+                continue;
+            const itemObj = item;
+            const itemTitle = String(itemObj.title ?? "Untitled");
+            const itemStatus = String(itemObj.status ?? "");
+            let bullet = `- ${itemTitle}`;
+            if (itemStatus)
+                bullet += ` \`[${itemStatus}]\``;
+            lines.push(bullet);
+            for (const criterion of itemAcceptance(itemObj)) {
+                if (criterion !== itemTitle)
+                    lines.push(`  - Acceptance: ${criterion}`);
+            }
+        }
+        lines.push("");
+    }
+    return lines;
+}
+function aggregateScopeSection(vbriefDir) {
+    const buckets = [];
+    for (const [folderName, heading] of LIFECYCLE_BUCKETS) {
+        let scopes = loadScopeVbriefs(join(vbriefDir, folderName));
+        if (folderName === "completed") {
+            scopes = scopes.filter(([, vb]) => {
+                const plan = vb.plan;
+                return (typeof plan === "object" &&
+                    plan !== null &&
+                    !Array.isArray(plan) &&
+                    plan.status === "completed");
+            });
+        }
+        if (scopes.length > 0)
+            buckets.push([folderName, heading, scopes]);
+    }
+    if (buckets.length === 0)
+        return [];
+    const lines = ["## Implementation Plan\n"];
+    for (const [, heading, scopes] of buckets) {
+        const depMap = crossScopeDepMap(scopes);
+        const ordered = topoSortScopes(scopes, depMap);
+        lines.push(`### ${heading}\n`);
+        for (const [stem, vbrief] of ordered)
+            lines.push(...renderScopeBlock(stem, vbrief));
+    }
+    return lines;
+}
+/** Render specification JSON to markdown (mirrors ``scripts/spec_render.render_spec``). */
+export function renderSpec(specPath, outPath, options = {}) {
+    const includeScopes = options.includeScopes ?? true;
+    const [ok, msg] = validateSpec(specPath);
+    if (!ok)
+        return [false, msg];
+    const spec = JSON.parse(readFileSync(specPath, "utf8"));
+    const plan = spec.plan;
+    let status = "";
+    if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
+        status = String(plan.status ?? "");
+    }
+    else {
+        status = String(spec.status ?? "");
+    }
+    if (!RENDERABLE_SPEC_STATUSES.has(status)) {
+        const renderable = [...RENDERABLE_SPEC_STATUSES].join(", ");
+        return [
+            false,
+            `⚠ specification.vbrief.json status is '${status}' (expected one of ${renderable})\n` +
+                "  Have the user review and set status to one of the renderable statuses before rendering.",
+        ];
+    }
+    const lines = [SPEC_RENDER_BANNER];
+    let title = "Specification";
+    if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
+        title = String(plan.title ?? "Specification");
+    }
+    else if (plan) {
+        title = String(plan);
+    }
+    else {
+        title = String(spec.title ?? "Specification");
+    }
+    lines.push(`# ${title}\n`);
+    let narratives = {};
+    if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
+        const n = plan.narratives;
+        if (typeof n === "object" && n !== null && !Array.isArray(n))
+            narratives = n;
+    }
+    else {
+        const legacy = spec.overview ?? spec.description ?? "";
+        if (legacy)
+            narratives = { Overview: legacy };
+    }
+    const renderedKeys = new Set();
+    for (const key of SPECIFICATION_NARRATIVE_KEY_ORDER) {
+        const val = narratives[key];
+        if (val) {
+            lines.push(`## ${key}\n`);
+            lines.push(`${String(val)}\n`);
+            renderedKeys.add(key);
+        }
+    }
+    for (const key of Object.keys(narratives).sort()) {
+        if (renderedKeys.has(key) || !narratives[key])
+            continue;
+        lines.push(`## ${key}\n`);
+        lines.push(`${String(narratives[key])}\n`);
+    }
+    const items = typeof plan === "object" && plan !== null && !Array.isArray(plan)
+        ? (plan.items ?? [])
+        : (spec.tasks ?? []);
+    if (Array.isArray(items)) {
+        for (const item of items) {
+            if (typeof item !== "object" || item === null || Array.isArray(item))
+                continue;
+            const itemObj = item;
+            const itemId = String(itemObj.id ?? "");
+            const titleText = String(itemObj.title ?? "");
+            const itemStatus = String(itemObj.status ?? "");
+            lines.push(`## ${itemId}: ${titleText}  \`[${itemStatus}]\`\n`);
+            let deps;
+            const metadata = itemObj.metadata;
+            if (typeof metadata === "object" && metadata !== null && !Array.isArray(metadata)) {
+                deps = metadata.dependencies;
+            }
+            if (!deps)
+                deps = itemObj.dependencies;
+            if (Array.isArray(deps) && deps.length > 0) {
+                lines.push(`**Depends on**: ${deps.map(String).join(", ")}\n`);
+            }
+            const narrative = itemObj.narrative;
+            if (typeof narrative === "object" && narrative !== null && !Array.isArray(narrative)) {
+                for (const [key, val] of Object.entries(narrative)) {
+                    if (key === "Traces")
+                        lines.push(`**Traces**: ${String(val)}\n`);
+                    else if (key === "Acceptance") {
+                        for (const line of splitAcceptance(val))
+                            lines.push(`- ${line}`);
+                        lines.push("");
+                    }
+                    else
+                        lines.push(`${String(val)}\n`);
+                }
+            }
+            else if (Array.isArray(narrative)) {
+                for (const entry of narrative)
+                    lines.push(`- ${String(entry)}`);
+                lines.push("");
+            }
+            else if (narrative) {
+                lines.push(`${String(narrative)}\n`);
+            }
+        }
+    }
+    if (includeScopes) {
+        const vbriefDir = resolve(dirname(specPath));
+        const scopeLines = aggregateScopeSection(vbriefDir);
+        if (scopeLines.length > 0)
+            lines.push(...scopeLines);
+    }
+    writeFileSync(outPath, lines.join("\n"), "utf8");
+    return [true, `✓ Rendered to ${outPath}`];
+}
+export function parseIncludeScopesFlag(argv) {
+    let includeScopes = true;
+    const remaining = [];
+    for (const arg of argv) {
+        if (arg === "--include-scopes") {
+            includeScopes = true;
+            continue;
+        }
+        if (arg.startsWith("--include-scopes=")) {
+            const value = arg.split("=", 2)[1]?.toLowerCase() ?? "";
+            includeScopes = value === "on" || value === "true" || value === "1" || value === "yes";
+            continue;
+        }
+        remaining.push(arg);
+    }
+    return { includeScopes, remaining };
+}
+/** CLI entry (mirrors ``scripts/spec_render.main``). */
+export function main(argv) {
+    const { includeScopes, remaining } = parseIncludeScopesFlag(argv);
+    if (remaining.length === 0) {
+        process.stderr.write("Usage: spec_render.py <spec_file> [out_file] [--include-scopes=on|off]\n");
+        return 2;
+    }
+    const specPath = remaining[0] ?? "";
+    const outPath = remaining.length >= 2
+        ? (remaining[1] ?? "")
+        : join(resolve(dirname(specPath)), "..", "SPECIFICATION.md");
+    const [ok, message] = renderSpec(specPath, outPath, { includeScopes });
+    process.stdout.write(`${message}\n`);
+    return ok ? 0 : 1;
+}
+//# sourceMappingURL=spec-render.js.map

package/dist/render/spec-validate.d.ts

@@ -0,0 +1,6 @@
+export type ValidateSpecResult = readonly [boolean, string];
+/** Validate the spec file at *specPath* (mirrors ``scripts/spec_validate.validate_spec``). */
+export declare function validateSpec(specPath: string): ValidateSpecResult;
+/** CLI entry (mirrors ``scripts/spec_validate.main``). */
+export declare function main(argv: readonly string[]): number;
+//# sourceMappingURL=spec-validate.d.ts.map

package/dist/render/spec-validate.js

@@ -0,0 +1,157 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { VALID_STATUSES, VALID_VBRIEF_VERSIONS } from "./constants.js";
+function validateNarratives(narratives, path, errors) {
+    if (typeof narratives !== "object" || narratives === null || Array.isArray(narratives)) {
+        errors.push(`${path} must be an object`);
+        return;
+    }
+    for (const [key, value] of Object.entries(narratives)) {
+        if (typeof value !== "string") {
+            errors.push(`${path}.${key} must be a string, got ${typeof value}`);
+        }
+    }
+}
+function validatePlanItem(item, path, errors) {
+    const itemId = typeof item.id === "string" ? item.id : "<no-id>";
+    const itemPath = `${path}[${itemId}]`;
+    if (!("title" in item))
+        errors.push(`${itemPath} missing 'title'`);
+    if (!("status" in item)) {
+        errors.push(`${itemPath} missing 'status'`);
+    }
+    else if (typeof item.status === "string" && !VALID_STATUSES.has(item.status)) {
+        errors.push(`${itemPath} invalid status: '${item.status}'`);
+    }
+    if ("narrative" in item) {
+        validateNarratives(item.narrative, `${itemPath}.narrative`, errors);
+    }
+    for (const nestedKey of ["items", "subItems"]) {
+        if (!(nestedKey in item))
+            continue;
+        const nested = item[nestedKey];
+        if (!Array.isArray(nested)) {
+            errors.push(`${itemPath}.${nestedKey} must be an array`);
+            continue;
+        }
+        for (let j = 0; j < nested.length; j += 1) {
+            const sub = nested[j];
+            if (typeof sub !== "object" || sub === null || Array.isArray(sub)) {
+                errors.push(`${itemPath}.${nestedKey}[${j}] must be an object`);
+                continue;
+            }
+            validatePlanItem(sub, `${itemPath}.${nestedKey}`, errors);
+        }
+    }
+}
+function validateSchema(data) {
+    const errors = [];
+    if (!("vBRIEFInfo" in data)) {
+        errors.push("missing required top-level key 'vBRIEFInfo'");
+    }
+    else {
+        const info = data.vBRIEFInfo;
+        if (typeof info !== "object" || info === null || Array.isArray(info)) {
+            errors.push("'vBRIEFInfo' must be an object");
+        }
+        else {
+            const version = info.version;
+            if (!VALID_VBRIEF_VERSIONS.has(String(version))) {
+                errors.push(`'vBRIEFInfo.version' must be '0.6' (canonical v0.6 schema, #533), got ${JSON.stringify(version)}. Run \`task migrate:vbrief\` to upgrade pre-existing v0.5 vBRIEFs in-place.`);
+            }
+        }
+    }
+    if (!("plan" in data)) {
+        errors.push("missing required top-level key 'plan'");
+    }
+    else {
+        const plan = data.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            errors.push("'plan' must be an object, not a string or other type");
+        }
+        else {
+            const planObj = plan;
+            for (const field of ["title", "status", "items"]) {
+                if (!(field in planObj))
+                    errors.push(`'plan' missing required field '${field}'`);
+            }
+            if ("title" in planObj) {
+                const title = planObj.title;
+                if (typeof title !== "string" || !title) {
+                    errors.push("'plan.title' must be a non-empty string");
+                }
+            }
+            if ("status" in planObj) {
+                const status = planObj.status;
+                if (typeof status === "string" && !VALID_STATUSES.has(status)) {
+                    errors.push(`'plan.status' invalid: '${status}' (expected one of ${[...VALID_STATUSES].sort().join(", ")})`);
+                }
+            }
+            if ("narratives" in planObj) {
+                validateNarratives(planObj.narratives, "plan.narratives", errors);
+            }
+            if ("items" in planObj) {
+                const items = planObj.items;
+                if (!Array.isArray(items)) {
+                    errors.push("'plan.items' must be an array");
+                }
+                else {
+                    for (let i = 0; i < items.length; i += 1) {
+                        const item = items[i];
+                        if (typeof item !== "object" || item === null || Array.isArray(item)) {
+                            errors.push(`plan.items[${i}] must be an object`);
+                            continue;
+                        }
+                        validatePlanItem(item, "plan.items", errors);
+                    }
+                }
+            }
+        }
+    }
+    const legacyKeys = ["vbrief", "tasks", "overview", "architecture"];
+    const foundLegacy = legacyKeys.filter((k) => k in data);
+    if (foundLegacy.length > 0) {
+        errors.push(`legacy flat-format keys found at top level: ${foundLegacy.sort().join(", ")}. Migrate to vBRIEF v0.6 envelope (vBRIEFInfo + plan)`);
+    }
+    return errors;
+}
+/** Validate the spec file at *specPath* (mirrors ``scripts/spec_validate.validate_spec``). */
+export function validateSpec(specPath) {
+    if (!existsSync(specPath)) {
+        return [
+            false,
+            `✗ ${specPath} not found\n` +
+                "  Create it by running the interview process (see deft/templates/make-spec.md)",
+        ];
+    }
+    let data;
+    try {
+        data = JSON.parse(readFileSync(specPath, "utf8"));
+    }
+    catch (exc) {
+        return [false, `✗ ${specPath} is not valid JSON: ${String(exc)}`];
+    }
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        return [false, `✗ ${basename(specPath)} has schema violations:\n  • root must be an object`];
+    }
+    const errors = validateSchema(data);
+    if (errors.length > 0) {
+        const detail = errors.map((e) => `  • ${e}`).join("\n");
+        return [false, `✗ ${basename(specPath)} has schema violations:\n${detail}`];
+    }
+    return [true, `✓ ${basename(specPath)} is valid vBRIEF`];
+}
+/** CLI entry (mirrors ``scripts/spec_validate.main``). */
+export function main(argv) {
+    if (argv.length < 1) {
+        process.stderr.write("Usage: spec_validate.py <spec_file>\n");
+        return 2;
+    }
+    const [ok, message] = validateSpec(argv[0] ?? "");
+    if (ok)
+        process.stdout.write(`${message}\n`);
+    else
+        process.stderr.write(`${message}\n`);
+    return ok ? 0 : 1;
+}
+//# sourceMappingURL=spec-validate.js.map

package/dist/render/text-utils.d.ts

@@ -0,0 +1,8 @@
+/** Split camelCase / PascalCase into lowercase words (linear; mirrors Python `_split_camel`). */
+export declare function splitCamel(name: string): string[];
+/** Tokenize on non-word chars (linear scanner; mirrors Python ``re.split(r"\\W+", ...)``). */
+export declare function splitWords(text: string): string[];
+/** Parse ``Phase N`` prefix for roadmap sorting (#641). */
+export declare function parsePhaseNumber(phaseName: string): number | null;
+export declare function phaseSortKey(phaseName: string): [number, number, string];
+//# sourceMappingURL=text-utils.d.ts.map

package/dist/render/text-utils.js

@@ -0,0 +1,72 @@
+/** Split camelCase / PascalCase into lowercase words (linear; mirrors Python `_split_camel`). */
+export function splitCamel(name) {
+    if (!name)
+        return [];
+    let spaced = "";
+    for (let i = 0; i < name.length; i += 1) {
+        const c = name[i] ?? "";
+        const prev = i > 0 ? (name[i - 1] ?? "") : "";
+        if (i > 0 && prev >= "a" && prev <= "z" && c >= "A" && c <= "Z") {
+            spaced += ` ${c}`;
+        }
+        else {
+            spaced += c;
+        }
+    }
+    return spaced
+        .split(" ")
+        .map((w) => w.toLowerCase())
+        .filter((w) => w.length > 0);
+}
+/** Tokenize on non-word chars (linear scanner; mirrors Python ``re.split(r"\\W+", ...)``). */
+export function splitWords(text) {
+    const words = [];
+    let current = "";
+    for (let i = 0; i < text.length; i += 1) {
+        const c = text[i] ?? "";
+        const isWord = (c >= "a" && c <= "z") || (c >= "A" && c <= "Z") || (c >= "0" && c <= "9") || c === "_";
+        if (isWord) {
+            current += c;
+        }
+        else if (current) {
+            words.push(current);
+            current = "";
+        }
+    }
+    if (current)
+        words.push(current);
+    return words;
+}
+/** Parse ``Phase N`` prefix for roadmap sorting (#641). */
+export function parsePhaseNumber(phaseName) {
+    const trimmed = phaseName.trimStart();
+    if (!trimmed.startsWith("Phase"))
+        return null;
+    let i = 5;
+    while (i < trimmed.length && trimmed[i] === " ")
+        i += 1;
+    let digits = "";
+    while (i < trimmed.length && trimmed.charCodeAt(i) >= 48 && trimmed.charCodeAt(i) <= 57) {
+        digits += trimmed[i] ?? "";
+        i += 1;
+    }
+    if (!digits)
+        return null;
+    if (i < trimmed.length) {
+        const next = trimmed[i] ?? "";
+        if ((next >= "a" && next <= "z") ||
+            (next >= "A" && next <= "Z") ||
+            (next >= "0" && next <= "9") ||
+            next === "_") {
+            return null;
+        }
+    }
+    return Number.parseInt(digits, 10);
+}
+export function phaseSortKey(phaseName) {
+    const num = parsePhaseNumber(phaseName);
+    if (num !== null)
+        return [0, num, phaseName];
+    return [1, 0, phaseName];
+}
+//# sourceMappingURL=text-utils.js.map

package/dist/scm/argv.d.ts

@@ -0,0 +1,7 @@
+/** Return `(present, remainder)` after removing every occurrence of `flag`. */
+export declare function extractFlag(extra: readonly string[], flag: string): [boolean, string[]];
+/** Return `(value, remainder)` for `--flag VALUE` or `--flag=VALUE`. */
+export declare function extractValueFlag(extra: readonly string[], flag: string, defaultValue?: string | null): [string | null, string[]];
+/** Project `obj` (dict or list[dict]) onto `fields`. */
+export declare function filterJsonFields(obj: unknown, fields: readonly string[]): unknown;
+//# sourceMappingURL=argv.d.ts.map

package/dist/scm/argv.js

@@ -0,0 +1,54 @@
+/** Return `(present, remainder)` after removing every occurrence of `flag`. */
+export function extractFlag(extra, flag) {
+    const present = extra.includes(flag);
+    const remainder = extra.filter((a) => a !== flag);
+    return [present, remainder];
+}
+/** Return `(value, remainder)` for `--flag VALUE` or `--flag=VALUE`. */
+export function extractValueFlag(extra, flag, defaultValue = null) {
+    const out = [];
+    let value = defaultValue;
+    let seen = false;
+    let i = 0;
+    while (i < extra.length) {
+        const token = extra[i];
+        if (!seen && token === flag && i + 1 < extra.length) {
+            value = extra[i + 1] ?? null;
+            seen = true;
+            i += 2;
+            continue;
+        }
+        if (!seen && token?.startsWith(`${flag}=`)) {
+            value = token.split("=", 2)[1] ?? null;
+            seen = true;
+            i += 1;
+            continue;
+        }
+        if (token !== undefined) {
+            out.push(token);
+        }
+        i += 1;
+    }
+    return [value, out];
+}
+/** Project `obj` (dict or list[dict]) onto `fields`. */
+export function filterJsonFields(obj, fields) {
+    if (fields.length === 0) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => filterJsonFields(item, fields));
+    }
+    if (obj !== null && typeof obj === "object") {
+        const record = obj;
+        const filtered = {};
+        for (const key of fields) {
+            if (key in record) {
+                filtered[key] = record[key];
+            }
+        }
+        return filtered;
+    }
+    return obj;
+}
+//# sourceMappingURL=argv.js.map

package/dist/scm/binary.d.ts

@@ -0,0 +1,11 @@
+export type WhichFn = (name: string) => string | null;
+/** Default PATH lookup mirroring Python `shutil.which`. Uses the
+ * platform-native resolver (`where` on Windows, `which` elsewhere) so
+ * executable resolution works cross-platform. */
+export declare function defaultWhich(name: string): string | null;
+/**
+ * Return `"ghx"` if on PATH, else `"gh"`; raise if neither is present.
+ * Mirrors `scripts/scm.py::resolve_binary`.
+ */
+export declare function resolveBinary(whichFn?: WhichFn): string;
+//# sourceMappingURL=binary.d.ts.map