@kbediako/codex-orchestrator 0.1.37 → 0.2.0

package/dist/scripts/design/pipeline/permit.js

@@ -18,6 +18,21 @@ export async function loadPermitFile(repoRoot) {
         };
     }
 }
+export function resolveRuntimeProofCapabilities(permitEntry) {
+    const runtimeProof = permitEntry && typeof permitEntry.runtime_proof === 'object' && permitEntry.runtime_proof !== null
+        ? permitEntry.runtime_proof
+        : {};
+    const screenshot = runtimeProof.allow_screenshot === true;
+    const externalLink = runtimeProof.allow_external_link === true;
+    const video = typeof runtimeProof.allow_video === 'boolean'
+        ? runtimeProof.allow_video === true
+        : permitEntry?.allow_video_capture === true;
+    return {
+        screenshot,
+        external_link: externalLink,
+        video
+    };
+}
 export function buildAllowedOriginSet(permit) {
     const allowed = new Set();
     const sources = Array.isArray(permit?.allowedSources) ? permit.allowedSources : [];

package/dist/scripts/lib/docs-catalog.js

@@ -0,0 +1,365 @@
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { pathExists, toPosixPath } from './docs-helpers.js';
+export const DEFAULT_DOCS_CATALOG_PATH = 'docs/docs-catalog.json';
+function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function normalizeString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function normalizeCatalogPath(value) {
+    const normalized = normalizeString(value).replace(/\\/g, '/');
+    if (!normalized) {
+        return '';
+    }
+    const withoutDotPrefix = normalized.replace(/^\.\//, '');
+    const collapsed = path.posix.normalize(withoutDotPrefix);
+    return collapsed === '.' ? '' : collapsed.replace(/^\.\//, '');
+}
+function normalizeStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.map((item) => normalizeString(item)).filter((item) => item.length > 0);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function globToRegExp(glob) {
+    let pattern = '^';
+    for (let index = 0; index < glob.length; index += 1) {
+        const char = glob[index];
+        const next = glob[index + 1];
+        const afterNext = glob[index + 2];
+        if (char === '*') {
+            if (next === '*') {
+                if (afterNext === '/') {
+                    pattern += '(?:.*/)?';
+                    index += 2;
+                }
+                else {
+                    pattern += '.*';
+                    index += 1;
+                }
+            }
+            else {
+                pattern += '[^/]*';
+            }
+            continue;
+        }
+        if (char === '?') {
+            pattern += '.';
+            continue;
+        }
+        pattern += escapeRegExp(char);
+    }
+    pattern += '$';
+    return new RegExp(pattern);
+}
+function normalizeCatalogRule(raw, kind) {
+    if (!isObject(raw)) {
+        throw new Error(`Invalid docs catalog ${kind}: expected object.`);
+    }
+    const pathValue = normalizeCatalogPath(raw.path);
+    const glob = normalizeCatalogPath(raw.glob);
+    if (kind === 'entry' && !pathValue) {
+        throw new Error('Invalid docs catalog entry: missing path.');
+    }
+    if (kind === 'pattern' && !glob) {
+        throw new Error('Invalid docs catalog pattern: missing glob.');
+    }
+    const cadenceDays = Number.isFinite(raw.cadence_days) ? Number(raw.cadence_days) : null;
+    const tier = Number.isFinite(raw.tier) ? Number(raw.tier) : null;
+    return {
+        path: pathValue,
+        glob,
+        glob_regex: glob ? globToRegExp(glob) : null,
+        status: normalizeString(raw.status) || 'active',
+        tier,
+        doc_class: normalizeString(raw.doc_class),
+        audience: normalizeString(raw.audience),
+        source_of_truth: normalizeStringArray(raw.source_of_truth),
+        owner: normalizeString(raw.owner),
+        cadence_days: cadenceDays,
+        update_triggers: normalizeStringArray(raw.update_triggers),
+        truth_checks: normalizeStringArray(raw.truth_checks)
+    };
+}
+function normalizeClassMap(raw) {
+    if (!isObject(raw)) {
+        return {};
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!isObject(value)) {
+            continue;
+        }
+        result[key] = {
+            label: normalizeString(value.label) || key,
+            report_order: Number.isFinite(value.report_order) ? Number(value.report_order) : 999
+        };
+    }
+    return result;
+}
+export async function loadDocsCatalog(repoRoot, relativePath = DEFAULT_DOCS_CATALOG_PATH) {
+    const absolutePath = path.resolve(repoRoot, relativePath);
+    const raw = JSON.parse(await readFile(absolutePath, 'utf8'));
+    return {
+        version: Number.isFinite(raw?.version) ? Number(raw.version) : 1,
+        relative_path: toPosixPath(path.relative(repoRoot, absolutePath)),
+        absolute_path: absolutePath,
+        classes: normalizeClassMap(raw?.classes),
+        policies: isObject(raw?.policies) ? raw.policies : {},
+        entries: Array.isArray(raw?.entries)
+            ? raw.entries.map((entry) => normalizeCatalogRule(entry, 'entry'))
+            : [],
+        patterns: Array.isArray(raw?.patterns)
+            ? raw.patterns.map((entry) => normalizeCatalogRule(entry, 'pattern'))
+            : []
+    };
+}
+export async function maybeLoadDocsCatalog(repoRoot, relativePath = DEFAULT_DOCS_CATALOG_PATH) {
+    const absolutePath = path.resolve(repoRoot, relativePath);
+    if (!(await pathExists(absolutePath))) {
+        return null;
+    }
+    return loadDocsCatalog(repoRoot, relativePath);
+}
+export function getDocsCatalogClassMeta(catalog, docClass) {
+    const meta = catalog?.classes?.[docClass];
+    if (!meta) {
+        return { label: docClass, report_order: 999 };
+    }
+    return {
+        label: normalizeString(meta.label) || docClass,
+        report_order: Number.isFinite(meta.report_order) ? Number(meta.report_order) : 999
+    };
+}
+export function resolveDocsCatalogEntry(docPath, catalog) {
+    const normalizedPath = normalizeCatalogPath(docPath);
+    if (!normalizedPath || !catalog) {
+        return null;
+    }
+    for (const entry of catalog.entries) {
+        if (entry.path === normalizedPath) {
+            return { ...entry, matched_by: 'path' };
+        }
+    }
+    for (const entry of catalog.patterns) {
+        if (entry.glob_regex?.test(normalizedPath)) {
+            return { ...entry, matched_by: 'glob' };
+        }
+    }
+    return null;
+}
+export function summarizeDocsByClass(items, catalog) {
+    const byClass = new Map();
+    function ensure(docClass) {
+        const key = docClass || 'uncatalogued';
+        if (!byClass.has(key)) {
+            const meta = getDocsCatalogClassMeta(catalog, key);
+            byClass.set(key, {
+                doc_class: key,
+                label: meta.label,
+                report_order: meta.report_order,
+                docs_scanned: 0,
+                registry_entries: 0,
+                missing_in_registry: 0,
+                missing_on_disk: 0,
+                invalid_entries: 0,
+                stale_entries: 0,
+                uncatalogued_docs: 0
+            });
+        }
+        return byClass.get(key);
+    }
+    for (const item of items) {
+        const bucket = ensure(item.doc_class);
+        if (item.metric === 'docs_scanned') {
+            bucket.docs_scanned += 1;
+        }
+        else if (item.metric === 'registry_entries') {
+            bucket.registry_entries += 1;
+        }
+        else if (item.metric === 'missing_in_registry') {
+            bucket.missing_in_registry += 1;
+        }
+        else if (item.metric === 'missing_on_disk') {
+            bucket.missing_on_disk += 1;
+        }
+        else if (item.metric === 'invalid_entries') {
+            bucket.invalid_entries += 1;
+        }
+        else if (item.metric === 'stale_entries') {
+            bucket.stale_entries += 1;
+        }
+        else if (item.metric === 'uncatalogued_docs') {
+            bucket.uncatalogued_docs += 1;
+        }
+    }
+    return [...byClass.values()].sort((left, right) => {
+        if (left.report_order !== right.report_order) {
+            return left.report_order - right.report_order;
+        }
+        return left.label.localeCompare(right.label);
+    });
+}
+export async function listBundledSkillNames(repoRoot) {
+    const skillsRoot = path.join(repoRoot, 'skills');
+    if (!(await pathExists(skillsRoot))) {
+        return [];
+    }
+    const entries = await readdir(skillsRoot, { withFileTypes: true });
+    const results = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const skillPath = path.join(skillsRoot, entry.name, 'SKILL.md');
+        if (await pathExists(skillPath)) {
+            results.push(entry.name);
+        }
+    }
+    results.sort();
+    return results;
+}
+export function extractBundledSkillNamesFromMarkdown(content, policy = {}) {
+    const lines = content.split('\n');
+    const sectionHeading = normalizeString(policy.section_heading) || '## Skills (bundled)';
+    const listIntro = normalizeString(policy.list_intro) || 'Bundled skills';
+    const sectionStart = lines.findIndex((line) => line.trim() === sectionHeading);
+    if (sectionStart === -1) {
+        return [];
+    }
+    let sectionEnd = lines.length;
+    for (let index = sectionStart + 1; index < lines.length; index += 1) {
+        if (lines[index]?.startsWith('## ')) {
+            sectionEnd = index;
+            break;
+        }
+    }
+    const sectionLines = lines.slice(sectionStart + 1, sectionEnd);
+    const rosterIntroIndex = sectionLines.findIndex((line) => line.trim().startsWith(listIntro));
+    if (rosterIntroIndex === -1) {
+        return [];
+    }
+    const results = [];
+    let started = false;
+    for (const line of sectionLines.slice(rosterIntroIndex + 1)) {
+        const trimmed = line.trim();
+        const match = /^- `([^`]+)`/.exec(trimmed);
+        if (match?.[1]) {
+            results.push(match[1]);
+            started = true;
+            continue;
+        }
+        if (started && trimmed.length > 0) {
+            break;
+        }
+    }
+    return [...new Set(results)].sort();
+}
+export async function readCurrentCodexPosture(repoRoot, policy = {}) {
+    const sourcePath = normalizeString(policy.source_path);
+    if (!sourcePath) {
+        return {
+            source_path: '',
+            cli_version: null,
+            model: null,
+            default_runtime: null,
+            explorer_fast_model: null,
+            unsupported_review_model: null
+        };
+    }
+    const absolutePath = path.resolve(repoRoot, sourcePath);
+    const content = await readFile(absolutePath, 'utf8');
+    const unsupportedReviewModel = /do not target delegated(?:\/review| or review)? surfaces at `([^`]+)`/i.exec(content)?.[1] ??
+        /delegated subagent and review surfaces on [^;\n]*; `([^`]+)` is currently unsupported there/i.exec(content)?.[1] ??
+        /delegated(?: subagent)?(?: and|\/) review surfaces on [^\n]* validates `([^`]+)`/i.exec(content)?.[1] ??
+        null;
+    return {
+        source_path: sourcePath,
+        cli_version: /Codex CLI\s+\(?`?([0-9]+\.[0-9]+\.[0-9]+)`?\)?/.exec(content)?.[1] ?? null,
+        model: /Current model posture(?: is|:)\s*`([^`]+)`/i.exec(content)?.[1] ?? null,
+        default_runtime: /Local ([A-Za-z0-9_-]+) remains the expected default runtime path/.exec(content)?.[1] ?? null,
+        explorer_fast_model: /explorer_fast[^\n]*`(gpt-[^`]+)`/i.exec(content)?.[1] ?? null,
+        unsupported_review_model: unsupportedReviewModel
+    };
+}
+export function extractCodexCliVersionMentions(content) {
+    const results = new Set();
+    const patterns = [
+        /Codex CLI\s+\(?`?([0-9]+\.[0-9]+\.[0-9]+)`?\)?/gi,
+        /codex-cli\s+\(?`?([0-9]+\.[0-9]+\.[0-9]+)`?\)?/gi
+    ];
+    for (const pattern of patterns) {
+        for (const match of content.matchAll(pattern)) {
+            if (match[1]) {
+                results.add(match[1]);
+            }
+        }
+    }
+    return [...results].sort();
+}
+export function extractCodexModelMentions(content) {
+    const results = new Set();
+    for (const match of content.matchAll(/\bgpt-[A-Za-z0-9.-]+\b/g)) {
+        if (match[0]) {
+            results.add(match[0]);
+        }
+    }
+    return [...results].sort();
+}
+function isModelPostureLine(line) {
+    return (isPrimaryModelPostureLine(line) ||
+        isSecondaryUnsupportedReviewReferenceLine(line) ||
+        /explorer_fast/i.test(line));
+}
+function isPrimaryModelPostureLine(line) {
+    return (/current model posture/i.test(line) ||
+        /keep delegated subagent and review surfaces on/i.test(line) ||
+        /keep delegated or review surfaces on/i.test(line) ||
+        /do not target delegated(?:\/review| or review)? surfaces at/i.test(line));
+}
+function isSecondaryUnsupportedReviewReferenceLine(line) {
+    return /for chatgpt auth,\s*this means/i.test(line);
+}
+export function extractModelPostureLines(content) {
+    return content
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => isModelPostureLine(line));
+}
+export function hasExpectedDefaultRuntimeLine(content, expectedRuntime) {
+    if (!normalizeString(expectedRuntime)) {
+        return true;
+    }
+    const relevantLines = content
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => /default runtime|expected default runtime path/i.test(line));
+    if (relevantLines.length === 0) {
+        return false;
+    }
+    const runtimePattern = new RegExp(`\\b${escapeRegExp(expectedRuntime)}\\b`, 'i');
+    return relevantLines.every((line) => runtimePattern.test(line));
+}
+export function hasExpectedModelPostureLine(content, expectedModel) {
+    if (!normalizeString(expectedModel)) {
+        return true;
+    }
+    const relevantLines = extractModelPostureLines(content).filter((line) => isPrimaryModelPostureLine(line));
+    if (relevantLines.length === 0) {
+        return false;
+    }
+    const modelPattern = new RegExp(`(^|[^A-Za-z0-9.-])${escapeRegExp(expectedModel)}($|[^A-Za-z0-9.-])`, 'i');
+    return relevantLines.every((line) => modelPattern.test(line));
+}
+export function countDocumentLines(content) {
+    const lines = content.split('\n');
+    return lines.at(-1) === '' ? lines.length - 1 : lines.length;
+}
+export function countHeadingLines(content, headingPrefix = '## ') {
+    return content.split('\n').filter((line) => line.startsWith(headingPrefix)).length;
+}

package/dist/scripts/lib/docs-helpers.js

@@ -1,8 +1,10 @@
+import { spawnSync } from 'node:child_process';
 import { access, readdir } from 'node:fs/promises';
 import path from 'node:path';
-const DOC_ROOTS = ['.agent', '.ai-dev-tasks', 'docs', 'tasks'];
+const DOC_ROOTS = ['.agent', '.ai-dev-tasks', 'docs', 'skills', 'tasks', 'templates'];
 const DOC_ROOT_FILES = ['README.md', 'AGENTS.md'];
 const EXCLUDED_DIR_NAMES = new Set(['.runs', 'out', 'archives', 'node_modules', 'dist']);
+const GIT_LS_FILES_MAX_BUFFER = 64 * 1024 * 1024;
 export async function pathExists(target, options = {}) {
     const { allowMissingOnly = false } = options;
     try {
@@ -55,23 +57,103 @@ export async function collectDocFiles(repoRoot) {
     results.sort();
     return results;
 }
+export function listTrackedFiles(repoRoot, pathspecs = []) {
+    const args = ['-C', repoRoot, 'ls-files', '-z'];
+    if (Array.isArray(pathspecs) && pathspecs.length > 0) {
+        args.push('--', ...pathspecs);
+    }
+    const git = spawnSync('git', args, {
+        encoding: 'utf8',
+        maxBuffer: GIT_LS_FILES_MAX_BUFFER
+    });
+    if (git.error || git.status !== 0) {
+        const detail = [
+            git.error?.message,
+            typeof git.stderr === 'string' ? git.stderr.trim() : '',
+            typeof git.stdout === 'string' ? git.stdout.trim() : '',
+            `status=${git.status ?? '<no status>'}`,
+            `signal=${git.signal ?? '<no signal>'}`
+        ]
+            .filter((part) => part)
+            .join('; ');
+        throw new Error(`git ls-files failed while collecting tracked files: ${detail}`);
+    }
+    return git.stdout
+        .split('\0')
+        .filter((line) => line.length > 0)
+        .map((line) => toPosixPath(line))
+        .sort();
+}
+function normalizeSlashPath(value) {
+    return value.replace(/\\/g, '/');
+}
+const SAFE_TASK_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-]*$/u;
+function normalizeTaskKeyCandidate(value) {
+    if (typeof value !== 'string') {
+        return '';
+    }
+    const normalized = value.trim();
+    if (!normalized || !SAFE_TASK_KEY_PATTERN.test(normalized)) {
+        return '';
+    }
+    return normalized;
+}
+function extractTaskKeyFromPath(value) {
+    if (typeof value !== 'string') {
+        return '';
+    }
+    const normalized = normalizeSlashPath(value.trim());
+    if (!normalized) {
+        return '';
+    }
+    const patterns = [
+        /^tasks\/tasks-([A-Za-z0-9][A-Za-z0-9-]*)\.md$/u,
+        /^tasks\/specs\/([A-Za-z0-9][A-Za-z0-9-]*)\.md$/u,
+        /^\.agent\/task\/([A-Za-z0-9][A-Za-z0-9-]*)\.md$/u
+    ];
+    for (const pattern of patterns) {
+        const match = normalized.match(pattern);
+        if (match?.[1]) {
+            return match[1];
+        }
+    }
+    return '';
+}
 export function normalizeTaskKey(item) {
     if (!item || typeof item !== 'object') {
         return null;
     }
     const id = typeof item.id === 'string' ? item.id.trim() : '';
     const slug = typeof item.slug === 'string' ? item.slug.trim() : '';
+    const taskPathCandidates = [
+        item?.paths?.task,
+        item?.relates_to,
+        item?.path,
+        item?.paths?.spec,
+        item?.paths?.agent_task
+    ];
+    const taskPathSlug = taskPathCandidates
+        .map((value) => extractTaskKeyFromPath(value))
+        .find((value) => value.length > 0) ?? '';
+    const datePrefixedIdMatch = id.match(/^\d{8}-([0-9]{4}-[A-Za-z0-9-]+)$/u);
+    const datePrefixedSlug = normalizeTaskKeyCandidate(datePrefixedIdMatch?.[1] ?? '');
     if (slug && id && slug.startsWith(`${id}-`)) {
-        return slug;
+        return normalizeTaskKeyCandidate(slug) || null;
     }
     if (id && slug) {
-        return `${id}-${slug}`;
+        return normalizeTaskKeyCandidate(`${id}-${slug}`) || null;
     }
     if (slug) {
-        return slug;
+        return normalizeTaskKeyCandidate(slug) || null;
+    }
+    if (taskPathSlug) {
+        return taskPathSlug;
+    }
+    if (datePrefixedSlug) {
+        return datePrefixedSlug;
     }
     if (id) {
-        return id;
+        return normalizeTaskKeyCandidate(id) || null;
     }
     return null;
 }