@kbediako/codex-orchestrator 0.1.2 → 0.1.3

package/dist/scripts/lib/cli-args.js

@@ -0,0 +1,53 @@
+export function parseArgs(argv) {
+    const args = {};
+    const positionals = [];
+    const entries = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const raw = argv[index];
+        if (!raw) {
+            continue;
+        }
+        if (raw === '--') {
+            positionals.push(...argv.slice(index + 1));
+            break;
+        }
+        if (!raw.startsWith('-')) {
+            positionals.push(raw);
+            continue;
+        }
+        const cleaned = raw.replace(/^--?/, '');
+        if (!cleaned) {
+            continue;
+        }
+        const [key, inlineValue] = cleaned.split('=');
+        if (inlineValue !== undefined) {
+            args[key] = inlineValue;
+            entries.push({ key, value: inlineValue });
+            continue;
+        }
+        const next = argv[index + 1];
+        if (next && !next.startsWith('-')) {
+            args[key] = next;
+            entries.push({ key, value: next });
+            index += 1;
+        }
+        else {
+            args[key] = true;
+            entries.push({ key, value: true });
+        }
+    }
+    return { args, positionals, entries };
+}
+export function hasFlag(args, key) {
+    const value = args[key];
+    if (value === undefined) {
+        return false;
+    }
+    if (value === false) {
+        return false;
+    }
+    if (value === 'false' || value === '0') {
+        return false;
+    }
+    return true;
+}

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

@@ -0,0 +1,111 @@
+import { access, readdir } from 'node:fs/promises';
+import path from 'node:path';
+const DOC_ROOTS = ['.agent', '.ai-dev-tasks', 'docs', 'tasks'];
+const DOC_ROOT_FILES = ['README.md', 'AGENTS.md'];
+const EXCLUDED_DIR_NAMES = new Set(['.runs', 'out', 'archives', 'node_modules', 'dist']);
+export async function pathExists(target, options = {}) {
+    const { allowMissingOnly = false } = options;
+    try {
+        await access(target);
+        return true;
+    }
+    catch (error) {
+        if (allowMissingOnly && error?.code !== 'ENOENT') {
+            throw error;
+        }
+        return false;
+    }
+}
+export function toPosixPath(value) {
+    return value.split(path.sep).join('/');
+}
+export async function collectMarkdownFiles(repoRoot, relativeDir) {
+    const absDir = path.join(repoRoot, relativeDir);
+    const entries = await readdir(absDir, { withFileTypes: true });
+    const results = [];
+    for (const entry of entries) {
+        const relPath = path.join(relativeDir, entry.name);
+        if (entry.isDirectory()) {
+            if (EXCLUDED_DIR_NAMES.has(entry.name)) {
+                continue;
+            }
+            results.push(...(await collectMarkdownFiles(repoRoot, relPath)));
+            continue;
+        }
+        if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+            results.push(toPosixPath(relPath));
+        }
+    }
+    return results;
+}
+export async function collectDocFiles(repoRoot) {
+    const results = [];
+    for (const file of DOC_ROOT_FILES) {
+        const abs = path.join(repoRoot, file);
+        if (await pathExists(abs)) {
+            results.push(toPosixPath(file));
+        }
+    }
+    for (const dir of DOC_ROOTS) {
+        const abs = path.join(repoRoot, dir);
+        if (await pathExists(abs)) {
+            results.push(...(await collectMarkdownFiles(repoRoot, dir)));
+        }
+    }
+    results.sort();
+    return results;
+}
+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() : '';
+    if (slug && id && slug.startsWith(`${id}-`)) {
+        return slug;
+    }
+    if (id && slug) {
+        return `${id}-${slug}`;
+    }
+    if (slug) {
+        return slug;
+    }
+    if (id) {
+        return id;
+    }
+    return null;
+}
+export function parseDateString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const match = value.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+    if (!match) {
+        return null;
+    }
+    return value;
+}
+export function parseIsoDate(raw) {
+    const normalized = parseDateString(raw);
+    if (!normalized) {
+        return null;
+    }
+    const [yearStr, monthStr, dayStr] = normalized.split('-');
+    const year = Number(yearStr);
+    const month = Number(monthStr) - 1;
+    const day = Number(dayStr);
+    const date = new Date(Date.UTC(year, month, day));
+    if (Number.isNaN(date.getTime())) {
+        return null;
+    }
+    if (date.getUTCFullYear() !== year ||
+        date.getUTCMonth() !== month ||
+        date.getUTCDate() !== day) {
+        return null;
+    }
+    return date;
+}
+export function computeAgeInDays(from, to) {
+    const msPerDay = 24 * 60 * 60 * 1000;
+    return Math.floor((to.getTime() - from.getTime()) / msPerDay);
+}

package/dist/scripts/lib/npm-pack.js

@@ -0,0 +1,20 @@
+import { execFile } from 'node:child_process';
+import process from 'node:process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export async function runPack() {
+    const { stdout } = await execFileAsync('npm', ['pack', '--json', '--ignore-scripts'], {
+        env: { ...process.env, npm_config_ignore_scripts: 'true' },
+        maxBuffer: 10 * 1024 * 1024
+    });
+    const trimmed = String(stdout ?? '').trim();
+    if (!trimmed) {
+        throw new Error('npm pack produced no output');
+    }
+    const parsed = JSON.parse(trimmed);
+    const record = Array.isArray(parsed) ? parsed[0] : parsed;
+    if (!record || typeof record !== 'object') {
+        throw new Error('npm pack output did not include a record');
+    }
+    return record;
+}

package/dist/scripts/lib/run-manifests.js

@@ -0,0 +1,160 @@
+import { access, readdir } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+import process from 'node:process';
+const DEFAULT_TASK_ID = '0101';
+function resolveRepoRoot() {
+    const configured = process.env.CODEX_ORCHESTRATOR_ROOT;
+    if (!configured) {
+        return process.cwd();
+    }
+    if (isAbsolute(configured)) {
+        return configured;
+    }
+    return resolve(process.cwd(), configured);
+}
+function resolveRunsDir(repoRoot) {
+    const configured = process.env.CODEX_ORCHESTRATOR_RUNS_DIR || '.runs';
+    if (isAbsolute(configured)) {
+        return configured;
+    }
+    return resolve(repoRoot, configured);
+}
+function resolveOutDir(repoRoot) {
+    const configured = process.env.CODEX_ORCHESTRATOR_OUT_DIR || 'out';
+    if (isAbsolute(configured)) {
+        return configured;
+    }
+    return resolve(repoRoot, configured);
+}
+export function resolveEnvironmentPaths() {
+    const repoRoot = resolveRepoRoot();
+    const runsRoot = resolveRunsDir(repoRoot);
+    const outRoot = resolveOutDir(repoRoot);
+    const taskId = process.env.MCP_RUNNER_TASK_ID ?? DEFAULT_TASK_ID;
+    return { repoRoot, runsRoot, outRoot, taskId };
+}
+export async function listDirectories(dirPath) {
+    try {
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+export function parseRunIdTimestamp(runId) {
+    if (typeof runId !== 'string') {
+        return null;
+    }
+    const match = runId.match(/^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z/);
+    if (!match) {
+        return null;
+    }
+    const [, date, hours, minutes, seconds, ms] = match;
+    const iso = `${date}T${hours}:${minutes}:${seconds}.${ms}Z`;
+    const parsed = new Date(iso);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+export function pickLatestRunId(runIds) {
+    if (!Array.isArray(runIds) || runIds.length === 0) {
+        return null;
+    }
+    const sorted = [...runIds].sort((a, b) => {
+        const aTimestamp = parseRunIdTimestamp(a)?.getTime();
+        const bTimestamp = parseRunIdTimestamp(b)?.getTime();
+        if (aTimestamp != null && bTimestamp != null && aTimestamp !== bTimestamp) {
+            return bTimestamp - aTimestamp;
+        }
+        return String(b ?? '').localeCompare(String(a ?? ''));
+    });
+    return sorted[0] ?? null;
+}
+export async function collectManifests(runsDir, taskFilter) {
+    const results = [];
+    let taskIds = [];
+    try {
+        taskIds = await readdir(runsDir);
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            return results;
+        }
+        throw error;
+    }
+    for (const taskId of taskIds) {
+        if (taskFilter && taskFilter !== taskId) {
+            continue;
+        }
+        const taskPath = join(runsDir, taskId);
+        const cliPath = join(taskPath, 'cli');
+        const legacyPath = taskPath;
+        const candidates = [];
+        try {
+            const cliRunIds = await readdir(cliPath);
+            candidates.push({ root: cliPath, runIds: cliRunIds });
+        }
+        catch {
+            // Ignore missing CLI directory; fall back to legacy layout.
+        }
+        if (candidates.length === 0) {
+            try {
+                const legacyRunIds = await readdir(legacyPath);
+                candidates.push({ root: legacyPath, runIds: legacyRunIds });
+            }
+            catch {
+                continue;
+            }
+        }
+        for (const candidate of candidates) {
+            for (const runId of candidate.runIds) {
+                const manifestPath = join(candidate.root, runId, 'manifest.json');
+                results.push(manifestPath);
+            }
+        }
+    }
+    return results;
+}
+export async function findSubagentManifests(runsDir, taskId) {
+    let entries;
+    try {
+        entries = await readdir(runsDir, { withFileTypes: true });
+    }
+    catch (error) {
+        const message = error && typeof error === 'object' && error !== null && 'message' in error
+            ? error.message
+            : String(error);
+        return { found: [], error: `Unable to read runs directory (${message})` };
+    }
+    const prefix = `${taskId}-`;
+    const found = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.startsWith(prefix)) {
+            continue;
+        }
+        const cliDir = join(runsDir, entry.name, 'cli');
+        let runDirs;
+        try {
+            runDirs = await readdir(cliDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const runDir of runDirs) {
+            if (!runDir.isDirectory()) {
+                continue;
+            }
+            const manifestPath = join(cliDir, runDir.name, 'manifest.json');
+            try {
+                await access(manifestPath);
+                found.push(manifestPath);
+            }
+            catch {
+                // ignore missing manifest
+            }
+        }
+    }
+    return { found, error: null };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbediako/codex-orchestrator",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "dist/orchestrator/**",
     "dist/packages/**",
     "dist/scripts/design/pipeline/**",
+    "dist/scripts/lib/**",
     "dist/types/**",
     "schemas/**",
     "templates/**",
@@ -32,12 +33,14 @@
     "build:patterns": "tsc -p patterns/tsconfig.json",
     "clean:dist": "node scripts/clean-dist.mjs",
     "docs:check": "node --loader ts-node/esm scripts/docs-hygiene.ts --check",
+    "docs:archive-implementation": "node scripts/implementation-docs-archive.mjs",
+    "docs:archive-tasks": "node scripts/tasks-archive.mjs",
+    "docs:freshness": "node scripts/docs-freshness.mjs --check",
     "docs:sync": "node --loader ts-node/esm scripts/docs-hygiene.ts --sync",
     "prelint": "node scripts/build-patterns-if-needed.mjs",
     "lint": "eslint orchestrator/src orchestrator/tests packages/orchestrator/src packages/orchestrator/tests packages/shared adapters evaluation/harness evaluation/tests --ext .ts,.tsx",
     "pack:audit": "node scripts/pack-audit.mjs",
     "pack:smoke": "node scripts/pack-smoke.mjs",
-    "parallel:goals": "node --loader ts-node/esm scripts/run-parallel-goals.ts",
     "prepack": "npm run clean:dist && npm run build && npm run pack:audit",
     "setup:design-tools": "node --loader ts-node/esm scripts/setup-design-tools.ts",
     "test": "npm run test:orchestrator",

package/dist/orchestrator/src/cli/pipelines/defaultDiagnostics.js

@@ -1,32 +0,0 @@
-export const defaultDiagnosticsPipeline = {
-    id: 'diagnostics',
-    title: 'Diagnostics Pipeline',
-    description: 'Build, lint, test, and optionally run spec-guard for the repository.',
-    tags: ['diagnostics-primary', 'diagnostics-secondary'],
-    stages: [
-        {
-            kind: 'command',
-            id: 'build',
-            title: 'npm run build',
-            command: 'npm run build'
-        },
-        {
-            kind: 'command',
-            id: 'lint',
-            title: 'npm run lint',
-            command: 'npm run lint'
-        },
-        {
-            kind: 'command',
-            id: 'test',
-            title: 'npm run test',
-            command: 'npm run test'
-        },
-        {
-            kind: 'command',
-            id: 'spec-guard',
-            title: 'Optional spec-guard (if scripts/spec-guard.mjs exists)',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/orchestrator/src/cli/utils/specGuardRunner.js" --dry-run'
-        }
-    ]
-};

package/dist/orchestrator/src/cli/pipelines/designReference.js

@@ -1,72 +0,0 @@
-const DESIGN_PIPELINE_ENV = {
-    DESIGN_PIPELINE: '1'
-};
-export const designReferencePipeline = {
-    id: 'design-reference',
-    title: 'Design Reference Pipeline',
-    description: 'Extracts design reference assets, stages Storybook-ready components, and records manifest evidence.',
-    tags: ['design', 'reference'],
-    stages: [
-        {
-            kind: 'command',
-            id: 'design-config',
-            title: 'Resolve design configuration',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/prepare.js"',
-            env: { ...DESIGN_PIPELINE_ENV }
-        },
-        {
-            kind: 'command',
-            id: 'design-extract',
-            title: 'Run Playwright design extractor',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/extract.js"',
-            env: { ...DESIGN_PIPELINE_ENV }
-        },
-        {
-            kind: 'command',
-            id: 'design-reference',
-            title: 'Build motherduck reference page',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/reference.js"',
-            env: { ...DESIGN_PIPELINE_ENV }
-        },
-        {
-            kind: 'command',
-            id: 'design-componentize',
-            title: 'Componentize artifacts via packages/design-system',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/componentize.js"',
-            env: { ...DESIGN_PIPELINE_ENV }
-        },
-        {
-            kind: 'command',
-            id: 'design-advanced-assets',
-            title: 'Generate advanced design assets',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/advanced-assets.js"',
-            env: { ...DESIGN_PIPELINE_ENV },
-            allowFailure: true,
-            summaryHint: 'Optional Framer Motion and FFmpeg assets'
-        },
-        {
-            kind: 'command',
-            id: 'design-visual-regression',
-            title: 'Run visual regression tests',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/visual-regression.js"',
-            env: { ...DESIGN_PIPELINE_ENV },
-            allowFailure: true,
-            summaryHint: 'Visual regression diffs stored under design/visual-regression/'
-        },
-        {
-            kind: 'command',
-            id: 'design-spec-guard',
-            title: 'Optional spec-guard (if scripts/spec-guard.mjs exists)',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/orchestrator/src/cli/utils/specGuardRunner.js" --dry-run',
-            env: { ...DESIGN_PIPELINE_ENV },
-            summaryHint: 'Ensures design specs are fresh before artifact write'
-        },
-        {
-            kind: 'command',
-            id: 'design-artifact-writer',
-            title: 'Persist design artifact manifests',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/write-artifacts.js"',
-            env: { ...DESIGN_PIPELINE_ENV }
-        }
-    ]
-};

package/dist/orchestrator/src/cli/pipelines/hiFiDesignToolkit.js

@@ -1,71 +0,0 @@
-const DESIGN_TOOLKIT_ENV = {
-    DESIGN_PIPELINE: '1',
-    DESIGN_TOOLKIT: '1'
-};
-export const hiFiDesignToolkitPipeline = {
-    id: 'hi-fi-design-toolkit',
-    title: 'Hi-Fi Design Toolkit',
-    description: 'Runs the hi-fi design toolkit pipeline to extract, tokenize, self-correct, and publish design artifacts.',
-    tags: ['design', 'hi-fi'],
-    stages: [
-        {
-            kind: 'command',
-            id: 'design-config',
-            title: 'Resolve design configuration',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/prepare.js"',
-            env: { ...DESIGN_TOOLKIT_ENV }
-        },
-        {
-            kind: 'command',
-            id: 'design-toolkit-extract',
-            title: 'Wrap external toolkit extractor',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/toolkit/extract.js"',
-            env: { ...DESIGN_TOOLKIT_ENV }
-        },
-        {
-            kind: 'command',
-            id: 'design-toolkit-tokens',
-            title: 'Generate tokens and style guides',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/toolkit/tokens.js"',
-            env: { ...DESIGN_TOOLKIT_ENV }
-        },
-        {
-            kind: 'command',
-            id: 'design-toolkit-reference',
-            title: 'Build reference pages + self-correction',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/toolkit/reference.js"',
-            env: { ...DESIGN_TOOLKIT_ENV }
-        },
-        {
-            kind: 'command',
-            id: 'design-advanced-assets',
-            title: 'Generate advanced design assets',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/advanced-assets.js"',
-            env: { ...DESIGN_TOOLKIT_ENV },
-            allowFailure: true,
-            summaryHint: 'Optional motion capture via Framer Motion + FFmpeg'
-        },
-        {
-            kind: 'command',
-            id: 'design-toolkit-publish',
-            title: 'Publish toolkit outputs to packages/design-system',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/toolkit/publish.js"',
-            env: { ...DESIGN_TOOLKIT_ENV }
-        },
-        {
-            kind: 'command',
-            id: 'design-spec-guard',
-            title: 'Optional spec-guard (if scripts/spec-guard.mjs exists)',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/orchestrator/src/cli/utils/specGuardRunner.js" --dry-run',
-            env: { ...DESIGN_TOOLKIT_ENV },
-            summaryHint: 'Ensures HI-FI design specs are current before artifact write'
-        },
-        {
-            kind: 'command',
-            id: 'design-artifact-writer',
-            title: 'Persist design manifests',
-            command: 'node "$CODEX_ORCHESTRATOR_PACKAGE_ROOT/dist/scripts/design/pipeline/write-artifacts.js"',
-            env: { ...DESIGN_TOOLKIT_ENV }
-        }
-    ]
-};

package/dist/orchestrator/src/cli/utils/jsonlWriter.js

@@ -1,10 +0,0 @@
-export class JsonlWriter {
-    stream;
-    constructor(stream = process.stdout) {
-        this.stream = stream;
-    }
-    write(event) {
-        const payload = `${JSON.stringify(event)}\n`;
-        this.stream.write(payload);
-    }
-}

package/dist/orchestrator/src/control-plane/index.js

@@ -1,3 +0,0 @@
-export { buildRunRequestV2 } from './request-builder.js';
-export { ControlPlaneDriftReporter } from './drift-reporter.js';
-export { ControlPlaneValidator, ControlPlaneValidationError } from './validator.js';

package/dist/orchestrator/src/persistence/identifierGuards.js

@@ -1 +0,0 @@
-export const WINDOWS_FORBIDDEN_CHARACTERS = new Set(['<', '>', ':', '"', '|', '?', '*']);

package/dist/orchestrator/src/persistence/writeAtomicFile.js

@@ -1,4 +0,0 @@
-import { writeAtomicFile as writeAtomicFileInternal } from '../utils/atomicWrite.js';
-export async function writeAtomicFile(destination, contents) {
-    await writeAtomicFileInternal(destination, contents, { ensureDir: false, encoding: 'utf-8' });
-}

package/dist/orchestrator/src/scheduler/index.js

@@ -1 +0,0 @@
-export { createSchedulerPlan, finalizeSchedulerPlan, serializeSchedulerPlan, buildSchedulerRunSummary } from './plan.js';