@kontourai/flow-agents 3.3.0 → 3.4.1

package/build/src/cli/kit.js

@@ -5,10 +5,11 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagBool, flagString } from "../lib/args.js";
-import { assertPathContained, copyDir, isoNow, readJson, walkFiles, writeJson } from "../lib/fs.js";
+import { assertPathContained, assertPathsDisjoint, atomicWriteJson, copyDirAtomic, ensureSafeDirectory, isoNow, readJson, walkFiles } from "../lib/fs.js";
 import { assertKitRepository, deriveKitTargets, parseKitDependencies } from "../flow-kit/validate.js";
 import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
 import { defaultCodexHome } from "../lib/local-artifact-root.js";
+import { root } from "../tools/common.js";
 const REGISTRY_REL = path.join("kits", "local", "installed-kits.json");
 const REPOSITORIES_REL = path.join("kits", "local", "repositories");
 function registryPath(dest) { return path.join(dest, REGISTRY_REL); }
@@ -17,6 +18,23 @@ function resolveDest(flags) {
     const explicit = flagString(flags, "dest");
     return path.resolve(explicit ?? defaultCodexHome());
 }
+function resolveCatalogKitSource(source) {
+    if (!/^[a-z][a-z0-9-]*$/.test(source))
+        return null;
+    const repoCatalogPath = path.join(root, "kits", "catalog.json");
+    if (!fs.existsSync(repoCatalogPath))
+        return null;
+    const catalog = readJson(repoCatalogPath);
+    const entry = Array.isArray(catalog.kits)
+        ? catalog.kits.find((item) => typeof item === "object" && item !== null && item.id === source)
+        : undefined;
+    if (!entry || typeof entry !== "object")
+        return null;
+    const rel = entry.path;
+    if (typeof rel !== "string")
+        return null;
+    return path.resolve(path.dirname(repoCatalogPath), "..", rel);
+}
 function loadRegistry(dest) {
     const file = registryPath(dest);
     if (!fs.existsSync(file))
@@ -96,7 +114,7 @@ async function install(argv) {
     if (isGitUrl) {
         return await installGitSource(source, argv);
     }
-    return await installLocalSource(path.resolve(source), argv);
+    return await installLocalSource(resolveCatalogKitSource(source) ?? path.resolve(source), argv);
 }
 async function installLocalSource(source, argv) {
     const args = parseArgs(argv);
@@ -112,13 +130,26 @@ async function installLocalSource(source, argv) {
         return 1;
     }
     const kitId = String(manifest.id);
+    const target = installedPath(dest, kitId);
+    try {
+        assertPathsDisjoint(source, target);
+        ensureSafeDirectory(dest, dest);
+        assertPathContained(dest, target);
+        ensureSafeDirectory(dest, path.dirname(target));
+        const registryFile = registryPath(dest);
+        ensureSafeDirectory(dest, path.dirname(registryFile));
+        if (fs.existsSync(registryFile) && fs.lstatSync(registryFile).isSymbolicLink()) {
+            throw new Error(`refusing to read or replace symlink: ${registryFile}`);
+        }
+    }
+    catch (error) {
+        console.error(`install: unsafe source or destination: ${error.message}`);
+        return 1;
+    }
     warnUninstalledDependencies(manifest, path.join(source, "kit.json"), dest);
     const hash = contentHash(source);
     const registry = loadRegistry(dest);
     const existing = registry.kits.find((entry) => entry.id === kitId);
-    const target = installedPath(dest, kitId);
-    fs.mkdirSync(dest, { recursive: true });
-    assertPathContained(dest, target);
     const sourceText = source;
     if (existing && existing.source !== sourceText && !flagBool(args.flags, "update")) {
         console.log(`conflict: kit '${kitId}' is already installed from ${existing.source}; rerun with --update to replace it`);
@@ -128,7 +159,7 @@ async function installLocalSource(source, argv) {
         console.log(`kit '${kitId}' is already installed from ${sourceText}`);
         return 0;
     }
-    copyDir(source, target);
+    copyDirAtomic(dest, source, target);
     const entry = {
         id: kitId,
         source: sourceText,
@@ -140,7 +171,7 @@ async function installLocalSource(source, argv) {
     if (typeof manifest.version === "string" && manifest.version)
         entry.version = manifest.version;
     registry.kits = existing ? registry.kits.map((item) => item.id === kitId ? entry : item) : [...registry.kits, entry];
-    writeJson(registryPath(dest), registry);
+    atomicWriteJson(dest, registryPath(dest), registry);
     console.log(`${existing ? "updated" : "installed"} local kit '${kitId}' at ${target}`);
     return 0;
 }
@@ -195,8 +226,20 @@ async function installGitSource(rawUrl, argv) {
         const registry = loadRegistry(dest);
         const existing = registry.kits.find((entry) => entry.id === kitId);
         const target = installedPath(dest, kitId);
-        fs.mkdirSync(dest, { recursive: true });
-        assertPathContained(dest, target);
+        try {
+            ensureSafeDirectory(dest, dest);
+            assertPathContained(dest, target);
+            ensureSafeDirectory(dest, path.dirname(target));
+            const registryFile = registryPath(dest);
+            ensureSafeDirectory(dest, path.dirname(registryFile));
+            if (fs.existsSync(registryFile) && fs.lstatSync(registryFile).isSymbolicLink()) {
+                throw new Error(`refusing to read or replace symlink: ${registryFile}`);
+            }
+        }
+        catch (error) {
+            console.error(`install: unsafe destination: ${error.message}`);
+            return 1;
+        }
         const sourceText = repoUrl + (ref ? `#${ref}` : "");
         if (existing && existing.source !== sourceText && !update) {
             console.log(`conflict: kit '${kitId}' is already installed from ${existing.source}; rerun with --update to replace it`);
@@ -206,7 +249,7 @@ async function installGitSource(rawUrl, argv) {
             console.log(`kit '${kitId}' is already installed from ${sourceText}`);
             return 0;
         }
-        copyDir(tmpBase, target);
+        copyDirAtomic(dest, tmpBase, target);
         const entry = {
             id: kitId,
             source: sourceText,
@@ -218,7 +261,7 @@ async function installGitSource(rawUrl, argv) {
         if (typeof manifest.version === "string" && manifest.version)
             entry.version = manifest.version;
         registry.kits = existing ? registry.kits.map((item) => item.id === kitId ? entry : item) : [...registry.kits, entry];
-        writeJson(registryPath(dest), registry);
+        atomicWriteJson(dest, registryPath(dest), registry);
         console.log(`${existing ? "updated" : "installed"} git kit '${kitId}' from ${sourceText} at ${target}`);
         return 0;
     }
@@ -313,7 +356,7 @@ async function inspect(argv) {
         return 1;
     }
     // Pass the real kitDir so @kontourai/flow can validate flow file existence for K0.
-    const result = await deriveKitTargets(manifest, kitDir);
+    const result = await deriveKitTargets(manifest, kitDir, root);
     console.log(JSON.stringify(result, null, 2));
     return result.conformance.k0 ? 0 : 1;
 }

package/build/src/cli/pull-work-provider.js

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagList, flagString } from "../lib/args.js";
 const FLOW_ARTIFACT_PATTERN = /(?<path>\.kontourai\/flow-agents\/[^\s`'")]+)/g;
@@ -11,6 +12,12 @@ const DAY_MS = 24 * 60 * 60 * 1000;
 function loadJson(file) {
     return file === "-" ? JSON.parse(fs.readFileSync(0, "utf8")) : JSON.parse(fs.readFileSync(file, "utf8"));
 }
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function arrayValue(value) {
+    return Array.isArray(value) ? value : [];
+}
 function names(values) {
     return Array.isArray(values) ? values.flatMap((item) => typeof item === "object" && item !== null && typeof item.name === "string" ? [item.name] : []) : [];
 }
@@ -18,7 +25,33 @@ function statusKey(value) {
     if (typeof value !== "string")
         return null;
     const key = value.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
-    return { todo: "todo", to_do: "todo", ready: "ready", doing: "in_progress", in_progress: "in_progress", blocked: "blocked", review: "review", verification: "verification", done: "done", closed: "done" }[key] ?? key;
+    return { open: "todo", todo: "todo", to_do: "todo", ready: "ready", doing: "in_progress", in_progress: "in_progress", blocked: "blocked", review: "review", verification: "verification", done: "done", closed: "done" }[key] ?? key;
+}
+function normalizedText(value) {
+    return typeof value === "string" && value.trim() ? value.trim().toLowerCase() : null;
+}
+function repoKey(owner, repo, number) {
+    const issueNumber = Number(number);
+    return typeof owner === "string" && typeof repo === "string" && Number.isFinite(issueNumber)
+        ? `${owner}/${repo}#${issueNumber}`
+        : null;
+}
+function configuredRepos(settings) {
+    const workProvider = settings.work_item_provider;
+    const boardProvider = (settings.board_provider ?? {});
+    const workRepo = workProvider.repo;
+    const board = (boardProvider.board ?? {});
+    const defaultOwner = stringValue(board.owner) ?? stringValue(boardProvider.repo?.owner) ?? workRepo.owner;
+    const workspace = asRecord(settings.workspace);
+    const repos = arrayValue(workspace?.repos).flatMap((repo) => {
+        if (typeof repo === "string" && repo.trim())
+            return [{ owner: defaultOwner, name: repo.trim() }];
+        const record = asRecord(repo);
+        const owner = stringValue(record?.owner) ?? defaultOwner;
+        const name = stringValue(record?.name);
+        return owner && name ? [{ owner, name }] : [];
+    });
+    return repos.length ? repos : [{ owner: workRepo.owner, name: workRepo.name }];
 }
 function projectStatus(issue) {
     for (const item of (Array.isArray(issue.projectItems) ? issue.projectItems : [])) {
@@ -393,6 +426,304 @@ function normalize(issue, settings) {
         created_at: issue.createdAt,
     };
 }
+function fieldValueByName(item, fieldName) {
+    const wanted = fieldName.toLowerCase();
+    const direct = item[fieldName] ?? item[fieldName.toLowerCase()];
+    if (typeof direct === "string")
+        return direct;
+    const fieldValues = Array.isArray(item.fieldValues) ? item.fieldValues : arrayValue(asRecord(item.fieldValues)?.nodes);
+    for (const value of fieldValues) {
+        const record = asRecord(value);
+        if (!record)
+            continue;
+        const field = asRecord(record.field);
+        const name = normalizedText(field?.name);
+        if (name !== wanted)
+            continue;
+        return stringValue(record.name) ?? stringValue(record.text) ?? stringValue(record.value) ?? stringValue(record.optionName);
+    }
+    return undefined;
+}
+function normalizeBoardIssue(rawIssue, fallbackOwner, fallbackRepo) {
+    const issue = asRecord(rawIssue);
+    if (!issue)
+        return null;
+    const number = Number(issue.number);
+    if (!Number.isFinite(number))
+        return null;
+    const repository = asRecord(issue.repository);
+    const owner = stringValue(issue.owner) ?? stringValue(asRecord(repository?.owner)?.login) ?? fallbackOwner;
+    const repo = stringValue(issue.repo) ?? stringValue(issue.repositoryName) ?? stringValue(repository?.name) ?? fallbackRepo;
+    return {
+        id: stringValue(issue.id),
+        node_id: stringValue(issue.node_id) ?? stringValue(issue.id),
+        owner,
+        repo,
+        number,
+        title: stringValue(issue.title) ?? `#${number}`,
+        body: stringValue(issue.body) ?? "",
+        state: stringValue(issue.state) ?? "OPEN",
+        labels: names(issue.labels).concat(arrayValue(asRecord(issue.labels)?.nodes).flatMap((label) => stringValue(asRecord(label)?.name) ?? [])),
+        url: stringValue(issue.url),
+        updatedAt: stringValue(issue.updatedAt),
+        createdAt: stringValue(issue.createdAt),
+    };
+}
+function normalizeBoardItem(rawItem, index, fallbackOwner, fallbackRepo) {
+    const item = asRecord(rawItem);
+    if (!item)
+        return null;
+    const content = item.content ?? item.issue;
+    const issue = normalizeBoardIssue(content, fallbackOwner, fallbackRepo);
+    if (!issue)
+        return null;
+    const rawPosition = item.position ?? item.databaseId ?? item.index;
+    const position = Number.isFinite(Number(rawPosition)) ? Number(rawPosition) : index;
+    return {
+        id: stringValue(item.id),
+        position,
+        status: fieldValueByName(item, "Status") ?? stringValue(item.status),
+        priority: fieldValueByName(item, "Priority") ?? stringValue(item.priority),
+        issue,
+    };
+}
+function boardItemsFromDoc(doc, settings) {
+    const workProvider = settings.work_item_provider;
+    const repo = workProvider.repo;
+    const record = asRecord(doc);
+    const rawItems = Array.isArray(doc)
+        ? doc
+        : arrayValue(record?.project_items).length ? arrayValue(record?.project_items)
+            : arrayValue(record?.projectItems).length ? arrayValue(record?.projectItems)
+                : arrayValue(record?.items).length ? arrayValue(record?.items)
+                    : arrayValue(asRecord(asRecord(asRecord(record?.data)?.organization)?.projectV2)?.items).length
+                        ? arrayValue(asRecord(asRecord(asRecord(record?.data)?.organization)?.projectV2)?.items)
+                        : [];
+    const nodes = rawItems.flatMap((item) => asRecord(item)?.nodes && Array.isArray(asRecord(item)?.nodes) ? arrayValue(asRecord(item)?.nodes) : [item]);
+    return nodes.flatMap((item, index) => normalizeBoardItem(item, index, repo.owner, repo.name) ?? []);
+}
+function openIssuesFromDoc(doc, settings) {
+    const repos = configuredRepos(settings);
+    const fallback = repos.length === 1 ? repos[0] : undefined;
+    const record = asRecord(doc);
+    const rawOpenIssues = record?.open_issues;
+    const rawIssues = arrayValue(rawOpenIssues).length ? arrayValue(rawOpenIssues)
+        : rawOpenIssues && typeof rawOpenIssues === "object" && !Array.isArray(rawOpenIssues)
+            ? Object.entries(rawOpenIssues).flatMap(([repoName, issues]) => arrayValue(issues).map((issue) => ({ issue, repoName })))
+            : arrayValue(record?.issues).length ? arrayValue(record?.issues)
+                : arrayValue(asRecord(asRecord(asRecord(record?.data)?.repository)?.issues)?.nodes);
+    return rawIssues.flatMap((issue) => {
+        const wrapped = asRecord(issue);
+        const rawIssue = wrapped && "issue" in wrapped ? wrapped.issue : issue;
+        const repoName = wrapped && typeof wrapped.repoName === "string" ? wrapped.repoName : undefined;
+        const repoFallback = repoName ? repos.find((repo) => repo.name === repoName) : fallback;
+        const normalized = normalizeBoardIssue(rawIssue, repoFallback?.owner, repoName ?? repoFallback?.name);
+        return normalized && (normalized.state ?? "OPEN").toUpperCase() === "OPEN" ? [normalized] : [];
+    });
+}
+function boardCandidate(item, settings) {
+    const workProvider = settings.work_item_provider;
+    const boardProvider = (settings.board_provider ?? {});
+    const issue = item.issue;
+    const owner = issue.owner ?? (workProvider.repo.owner);
+    const repo = issue.repo ?? (workProvider.repo.name);
+    const body = issue.body ?? "";
+    const metadata = parseWorkItemMetadata(body);
+    const rawStatus = item.status ?? "Todo";
+    return {
+        id: `github:${owner}/${repo}#${issue.number}`,
+        title: issue.title,
+        body,
+        status: statusKey(rawStatus) ?? rawStatus.toLowerCase(),
+        labels: issue.labels,
+        priority: item.priority,
+        ...sourceRevisionFields(metadata, owner, repo),
+        blockers: mergeBlockers(normalizeStructuredBlockers(metadata, owner, repo), blockers(body, owner, repo)),
+        related_links: extractRefs(body, owner, repo),
+        source_provider: { role: "WorkItemProvider", kind: workProvider.kind, owner, repo, number: issue.number, url: issue.url, state: issue.state, node_id: issue.node_id ?? issue.id, capabilities: workProvider.capabilities ?? [] },
+        board_membership: {
+            role: "BoardProvider",
+            kind: boardProvider.kind,
+            board: boardProvider.board,
+            project_item_id: item.id,
+            position: item.position,
+            status: rawStatus,
+            priority: item.priority,
+            capabilities: boardProvider.capabilities ?? [],
+        },
+        artifact_refs: Array.from(body.matchAll(FLOW_ARTIFACT_PATTERN), (m) => (m.groups?.path ?? "").replace(/[.,]+$/, "")),
+        updated_at: issue.updatedAt,
+        created_at: issue.createdAt,
+    };
+}
+function priorityRank(priority) {
+    const key = String(priority ?? "").trim().toUpperCase();
+    return { P0: 0, P1: 1, P2: 2 }[key] ?? 99;
+}
+function boardResult(settings, boardItems, openIssues) {
+    const selection = (settings.selection ?? {});
+    const filters = (selection.filters ?? {});
+    const readyStatuses = new Set((filters.ready_statuses ?? ["ready"]).map((status) => status.toLowerCase()));
+    const workProvider = settings.work_item_provider;
+    const repo = workProvider.repo;
+    const candidates = boardItems.map((item) => ({ item, candidate: boardCandidate(item, settings) }));
+    const readyQueue = candidates
+        .filter(({ item }) => readyStatuses.has(String(statusKey(item.status) ?? item.status ?? "").toLowerCase()))
+        .sort((left, right) => priorityRank(left.item.priority) - priorityRank(right.item.priority) || left.item.position - right.item.position)
+        .map(({ candidate }) => candidate);
+    const boardIssueKeys = new Set(boardItems.flatMap((item) => {
+        const issue = item.issue;
+        const key = repoKey(issue?.owner ?? repo.owner, issue?.repo ?? repo.name, issue?.number);
+        return key ? [key] : [];
+    }));
+    const intakeGaps = openIssues
+        .filter((issue) => !boardIssueKeys.has(repoKey(issue.owner ?? repo.owner, issue.repo ?? repo.name, issue.number) ?? ""))
+        .map((issue) => ({
+        id: `github:${issue.owner ?? repo.owner}/${issue.repo ?? repo.name}#${issue.number}`,
+        title: issue.title,
+        status: statusKey(issue.state) ?? "todo",
+        labels: issue.labels,
+        source_provider: { role: "WorkItemProvider", kind: workProvider.kind, owner: issue.owner ?? repo.owner, repo: issue.repo ?? repo.name, number: issue.number, url: issue.url, state: issue.state, node_id: issue.node_id ?? issue.id, capabilities: workProvider.capabilities ?? [] },
+    }));
+    const warnings = readyQueue.length === 0
+        ? [{ code: "zero_ready_items", message: "Configured BoardProvider yielded zero ready items; treat this as a dead readiness source and do not silently fall back to WorkItemProvider issue listing." }]
+        : [];
+    return { ready_queue: readyQueue, intake_gaps: intakeGaps, warnings };
+}
+const PROJECT_BOARD_QUERY = `
+query($org: String!, $projectNumber: Int!, $repoOwner: String!, $repoName: String!, $itemCursor: String, $issueCursor: String) {
+  organization(login: $org) {
+    projectV2(number: $projectNumber) {
+      items(first: 100, after: $itemCursor) {
+        pageInfo { hasNextPage endCursor }
+        nodes {
+          id
+          fieldValues(first: 30) {
+            nodes {
+              ... on ProjectV2ItemFieldSingleSelectValue { name field { ... on ProjectV2FieldCommon { name } } }
+              ... on ProjectV2ItemFieldTextValue { text field { ... on ProjectV2FieldCommon { name } } }
+            }
+          }
+          content {
+            ... on Issue {
+              id
+              number
+              title
+              body
+              state
+              url
+              updatedAt
+              createdAt
+              repository { name owner { login } }
+              labels(first: 50) { nodes { name } }
+            }
+          }
+        }
+      }
+    }
+  }
+  repository(owner: $repoOwner, name: $repoName) {
+    issues(first: 100, after: $issueCursor, states: OPEN) {
+      pageInfo { hasNextPage endCursor }
+      nodes {
+        id
+        number
+        title
+        body
+        state
+        url
+        updatedAt
+        createdAt
+        repository { name owner { login } }
+        labels(first: 50) { nodes { name } }
+      }
+    }
+  }
+}`;
+const REPO_ISSUES_QUERY = `
+query($repoOwner: String!, $repoName: String!, $issueCursor: String) {
+  repository(owner: $repoOwner, name: $repoName) {
+    issues(first: 100, after: $issueCursor, states: OPEN) {
+      pageInfo { hasNextPage endCursor }
+      nodes {
+        id
+        number
+        title
+        body
+        state
+        url
+        updatedAt
+        createdAt
+        repository { name owner { login } }
+        labels(first: 50) { nodes { name } }
+      }
+    }
+  }
+}`;
+function ghGraphql(query, variables) {
+    const args = ["api", "graphql", "-f", `query=${query}`];
+    for (const [key, value] of Object.entries(variables)) {
+        if (value !== undefined && value !== "")
+            args.push("-F", `${key}=${value}`);
+    }
+    return JSON.parse(execFileSync("gh", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }));
+}
+function liveBoardDoc(settings) {
+    const workProvider = settings.work_item_provider;
+    const boardProvider = settings.board_provider;
+    const workRepo = workProvider.repo;
+    const repos = configuredRepos(settings);
+    const board = boardProvider.board;
+    const org = stringValue(board.owner) ?? stringValue(boardProvider.repo?.owner) ?? workRepo.owner;
+    const projectNumber = Number(board.number);
+    if (!org || !Number.isFinite(projectNumber))
+        throw new Error("BoardProvider must configure board.owner or repo.owner and board.number for live reads");
+    const items = [];
+    const issues = [];
+    let itemCursor = "";
+    let issueCursor = "";
+    let fetchItems = true;
+    let fetchIssues = true;
+    while (fetchItems || fetchIssues) {
+        const page = ghGraphql(PROJECT_BOARD_QUERY, {
+            org,
+            projectNumber,
+            repoOwner: repos[0]?.owner ?? workRepo.owner,
+            repoName: repos[0]?.name ?? workRepo.name,
+            itemCursor,
+            issueCursor,
+        });
+        const projectItems = asRecord(asRecord(asRecord(page.data)?.organization)?.projectV2)?.items;
+        const repoIssues = asRecord(asRecord(page.data)?.repository)?.issues;
+        if (fetchItems)
+            items.push(...arrayValue(projectItems?.nodes));
+        if (fetchIssues)
+            issues.push(...arrayValue(repoIssues?.nodes));
+        const itemPageInfo = asRecord(projectItems?.pageInfo);
+        const issuePageInfo = asRecord(repoIssues?.pageInfo);
+        fetchItems = Boolean(itemPageInfo?.hasNextPage);
+        fetchIssues = Boolean(issuePageInfo?.hasNextPage);
+        itemCursor = stringValue(itemPageInfo?.endCursor) ?? "";
+        issueCursor = stringValue(issuePageInfo?.endCursor) ?? "";
+    }
+    for (const repo of repos.slice(1)) {
+        let repoIssueCursor = "";
+        let fetchRepoIssues = true;
+        while (fetchRepoIssues) {
+            const page = ghGraphql(REPO_ISSUES_QUERY, {
+                repoOwner: repo.owner,
+                repoName: repo.name,
+                issueCursor: repoIssueCursor,
+            });
+            const repoIssues = asRecord(asRecord(page.data)?.repository)?.issues;
+            issues.push(...arrayValue(repoIssues?.nodes));
+            const issuePageInfo = asRecord(repoIssues?.pageInfo);
+            fetchRepoIssues = Boolean(issuePageInfo?.hasNextPage);
+            repoIssueCursor = stringValue(issuePageInfo?.endCursor) ?? "";
+        }
+    }
+    return { items, issues };
+}
 function classify(item, settings, resolved) {
     const selection = (settings.selection ?? {});
     const filters = (selection.filters ?? {});
@@ -434,16 +765,21 @@ function resolveSettings(doc) {
         return doc;
     if (Array.isArray(doc.projects) && doc.projects.length)
         return doc.projects[0];
-    if (typeof doc.defaults === "object" && doc.defaults !== null)
-        return doc.defaults;
+    if (typeof doc.defaults === "object" && doc.defaults !== null) {
+        const settings = structuredClone(doc.defaults);
+        if (typeof doc.workspace === "object" && doc.workspace !== null)
+            settings.workspace = doc.workspace;
+        return settings;
+    }
     throw new Error("settings JSON must be an effective settings object or backlog-provider-settings document");
 }
 export function main(argv = process.argv.slice(2)) {
     const args = parseArgs(argv);
     const settingsJson = flagString(args.flags, "settings-json");
     const issuesJson = flagString(args.flags, "issues-json");
-    if (!settingsJson || !issuesJson)
-        throw new Error("--settings-json and --issues-json are required");
+    const itemsJson = flagString(args.flags, "items-json");
+    if (!settingsJson)
+        throw new Error("--settings-json is required");
     const now = new Date(flagString(args.flags, "now") ?? Date.now());
     if (Number.isNaN(now.getTime()))
         throw new Error("--now must be a valid date/time when provided");
@@ -455,6 +791,11 @@ export function main(argv = process.argv.slice(2)) {
         now,
     };
     const settings = resolveSettings(loadJson(settingsJson));
+    if (itemsJson || !issuesJson) {
+        const doc = itemsJson ? loadJson(itemsJson) : liveBoardDoc(settings);
+        console.log(JSON.stringify(boardResult(settings, boardItemsFromDoc(doc, settings), openIssuesFromDoc(doc, settings)), null, 2));
+        return 0;
+    }
     const issuesDoc = loadJson(issuesJson);
     const issues = Array.isArray(issuesDoc) ? issuesDoc : (issuesDoc.items ?? [issuesDoc]);
     const resolved = Object.fromEntries(flagList(args.flags, "resolved-ref").map((item) => item.split("=", 2)));

package/build/src/cli/skill-drift-check.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): Promise<number>;