@kbediako/codex-orchestrator 0.1.0

package/dist/packages/shared/manifest/toolRuns.js

@@ -0,0 +1,78 @@
+import { loadJsonManifest, resolveIO, writeJsonManifest } from './fileIO.js';
+export function sanitizeToolRunRecord(record) {
+    const { metadata, ...rest } = record;
+    const sanitized = {
+        ...rest,
+        metadata: metadata ? { ...metadata } : undefined,
+        events: record.events ? record.events.map(sanitizeToolRunEvent) : undefined
+    };
+    if (!sanitized.id) {
+        throw new Error('Tool run record must include an id.');
+    }
+    if (!sanitized.tool) {
+        throw new Error(`Tool run ${sanitized.id} must include a tool identifier.`);
+    }
+    if (sanitized.retryCount < 0) {
+        sanitized.retryCount = 0;
+    }
+    if (sanitized.attemptCount < 1) {
+        sanitized.attemptCount = 1;
+    }
+    return sanitized;
+}
+export function sanitizeToolRunEvent(event) {
+    if (!event.timestamp) {
+        throw new Error('Tool run events must include a timestamp.');
+    }
+    if (!event.correlationId) {
+        throw new Error('Tool run events must include a correlationId.');
+    }
+    if (event.attempt < 1) {
+        throw new Error('Tool run events must reference an attempt greater than or equal to 1.');
+    }
+    switch (event.type) {
+        case 'exec:begin':
+            return { ...event };
+        case 'exec:chunk': {
+            const sequence = event.sequence ?? null;
+            if (sequence === null || sequence < 1) {
+                throw new Error('exec:chunk events must have a positive sequence value.');
+            }
+            const bytes = event.bytes ?? null;
+            if (bytes !== null && bytes < 0) {
+                throw new Error('exec:chunk events must report a non-negative byte count.');
+            }
+            return { ...event, sequence, bytes };
+        }
+        case 'exec:end':
+            return { ...event };
+        case 'exec:retry': {
+            const delayMs = event.delayMs ?? null;
+            if (delayMs !== null && delayMs < 0) {
+                throw new Error('exec:retry events must report a non-negative delay.');
+            }
+            return { ...event, delayMs };
+        }
+        default:
+            return { ...event };
+    }
+}
+export function mergeToolRunRecord(manifest, record) {
+    const sanitized = sanitizeToolRunRecord(record);
+    const existingRuns = Array.isArray(manifest.toolRuns) ? [...manifest.toolRuns] : [];
+    const index = existingRuns.findIndex((entry) => entry.id === sanitized.id);
+    if (index >= 0) {
+        existingRuns[index] = { ...existingRuns[index], ...sanitized };
+    }
+    else {
+        existingRuns.push(sanitized);
+    }
+    return { ...manifest, toolRuns: existingRuns };
+}
+export async function persistToolRunRecord(manifestPath, record, options = {}) {
+    const io = resolveIO(options);
+    const manifest = (await loadJsonManifest(manifestPath, io)) ?? {};
+    const merged = mergeToolRunRecord(manifest, record);
+    await writeJsonManifest(manifestPath, merged, io);
+    return merged.toolRuns.find((entry) => entry.id === record.id);
+}

package/dist/packages/shared/manifest/toolkitArtifacts.js

@@ -0,0 +1,223 @@
+import { sanitizeRelativeArtifactPath } from './artifactUtils.js';
+const TOOLKIT_STAGE_SET = new Set([
+    'extract',
+    'tokens',
+    'styleguide',
+    'reference',
+    'self-correct',
+    'publish'
+]);
+const MAX_TOOLKIT_ARTIFACTS = 200;
+export function mergeToolkitArtifacts(existing, incoming) {
+    const sanitizedExisting = existing
+        .map((entry) => {
+        try {
+            return sanitizeToolkitArtifactRecord(entry);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((entry) => entry !== null);
+    const merged = [...sanitizedExisting];
+    for (const record of incoming) {
+        const sanitized = sanitizeToolkitArtifactRecord(record);
+        const index = merged.findIndex((entry) => entry.id === sanitized.id &&
+            entry.stage === sanitized.stage &&
+            entry.relative_path === sanitized.relative_path);
+        if (index >= 0) {
+            merged[index] = { ...merged[index], ...sanitized };
+        }
+        else {
+            merged.push(sanitized);
+        }
+    }
+    if (merged.length > MAX_TOOLKIT_ARTIFACTS) {
+        return merged.slice(-MAX_TOOLKIT_ARTIFACTS);
+    }
+    return merged;
+}
+export function sanitizeToolkitArtifactRecord(record) {
+    if (!record || typeof record !== 'object') {
+        throw new Error('design toolkit artifact record must be an object');
+    }
+    const input = record;
+    const id = coerceToolkitString(input.id);
+    if (!id) {
+        throw new Error('design toolkit artifact record must include an id');
+    }
+    const stage = input.stage;
+    if (typeof stage !== 'string' || !TOOLKIT_STAGE_SET.has(stage)) {
+        throw new Error(`invalid design toolkit artifact stage '${String(stage)}'`);
+    }
+    const status = input.status;
+    if (status !== 'succeeded' && status !== 'failed' && status !== 'skipped') {
+        throw new Error(`invalid design toolkit artifact status '${String(status)}'`);
+    }
+    const path = coerceToolkitString(input.relative_path);
+    if (!path) {
+        throw new Error('design toolkit artifact must include a relative_path string');
+    }
+    const artifact = {
+        id,
+        stage: stage,
+        status: status,
+        relative_path: sanitizeRelativeArtifactPath(path)
+    };
+    const description = coerceToolkitString(input.description);
+    if (description) {
+        artifact.description = description;
+    }
+    if (Array.isArray(input.approvals)) {
+        const approvals = input.approvals
+            .map((entry) => sanitizeApprovalRecord(entry))
+            .filter((entry) => Boolean(entry));
+        if (approvals.length > 0) {
+            artifact.approvals = approvals;
+        }
+    }
+    if (input.retention && typeof input.retention === 'object') {
+        const retention = input.retention;
+        const days = coerceNumber(retention.days, null, {
+            min: 1
+        });
+        const expiry = coerceToolkitString(retention.expiry);
+        if (days !== null && expiry) {
+            artifact.retention = {
+                days,
+                autoPurge: coerceBoolean(retention.auto_purge ?? retention.autoPurge, false),
+                expiry,
+                policy: coerceToolkitString(retention.policy) ?? undefined
+            };
+        }
+    }
+    if (input.metrics && typeof input.metrics === 'object') {
+        artifact.metrics = sanitizeToolkitMetrics(input.metrics);
+    }
+    if (Array.isArray(input.privacy_notes)) {
+        const notes = input.privacy_notes
+            .map((value) => (typeof value === 'string' ? value.trim() : ''))
+            .filter((value) => value.length > 0);
+        if (notes.length > 0) {
+            artifact.privacy_notes = notes.slice(0, 10);
+        }
+    }
+    return artifact;
+}
+export function sanitizeToolkitSummary(summary) {
+    const stages = (summary.stages ?? []).map((entry) => {
+        const artifacts = Number(entry.artifacts ?? 0);
+        return {
+            stage: entry.stage,
+            artifacts: Number.isFinite(artifacts) && artifacts >= 0 ? artifacts : 0,
+            metrics: sanitizeToolkitMetrics(entry.metrics),
+            notes: Array.isArray(entry.notes)
+                ? entry.notes.map((note) => (typeof note === 'string' ? note.trim() : '')).filter((note) => note.length > 0)
+                : undefined
+        };
+    });
+    const approvals = Array.isArray(summary.approvals)
+        ? summary.approvals
+            .map((value) => (typeof value === 'string' ? value.trim() : ''))
+            .filter((value) => value.length > 0)
+        : undefined;
+    return {
+        generated_at: coerceToolkitString(summary.generated_at) ?? new Date().toISOString(),
+        stages,
+        totals: sanitizeToolkitNumericMetrics(summary.totals),
+        approvals
+    };
+}
+export function sanitizeToolkitMetrics(record) {
+    if (!record || typeof record !== 'object') {
+        return undefined;
+    }
+    const sanitized = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (!key) {
+            continue;
+        }
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            sanitized[key] = value;
+        }
+        else if (typeof value === 'string') {
+            const trimmed = value.trim();
+            if (trimmed.length > 0) {
+                sanitized[key] = trimmed;
+            }
+        }
+    }
+    return Object.keys(sanitized).length > 0 ? sanitized : undefined;
+}
+export function sanitizeToolkitNumericMetrics(record) {
+    if (!record || typeof record !== 'object') {
+        return undefined;
+    }
+    const sanitized = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (!key) {
+            continue;
+        }
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            sanitized[key] = value;
+        }
+    }
+    return Object.keys(sanitized).length > 0 ? sanitized : undefined;
+}
+function sanitizeApprovalRecord(entry) {
+    if (!entry || typeof entry !== 'object') {
+        return null;
+    }
+    const record = entry;
+    const id = typeof record.id === 'string' ? record.id.trim() : '';
+    const actor = typeof record.actor === 'string' ? record.actor.trim() : '';
+    const reason = typeof record.reason === 'string' ? record.reason.trim() : '';
+    const timestamp = typeof record.timestamp === 'string' ? record.timestamp.trim() : '';
+    if (!id || !actor || !timestamp) {
+        return null;
+    }
+    return {
+        id,
+        actor,
+        reason,
+        timestamp
+    };
+}
+function coerceToolkitString(value) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    return null;
+}
+function coerceNumber(value, fallback, options = {}) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        const numeric = options.min !== undefined ? Math.max(options.min, value) : value;
+        return numeric;
+    }
+    if (typeof value === 'string' && value.trim().length > 0) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return options.min !== undefined ? Math.max(options.min, parsed) : parsed;
+        }
+    }
+    return fallback ?? null;
+}
+function coerceBoolean(value, fallback) {
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        return value !== 0;
+    }
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        if (['true', '1', 'yes', 'on'].includes(normalized)) {
+            return true;
+        }
+        if (['false', '0', 'no', 'off'].includes(normalized)) {
+            return false;
+        }
+    }
+    return fallback;
+}

package/dist/packages/shared/manifest/types.js

@@ -0,0 +1,5 @@
+/**
+ * THIS FILE IS AUTO-GENERATED.
+ * Run "npm run generate:manifest-types" after editing schemas/manifest.json.
+ */
+export {};

package/dist/packages/shared/manifest/validator.js

@@ -0,0 +1,73 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Ajv as AjvCtor } from 'ajv';
+const ajv = new AjvCtor({
+    allErrors: true,
+    strict: false
+});
+const manifestSchema = loadManifestSchema();
+const validate = ajv.compile(manifestSchema);
+export const manifestValidator = validate;
+export function getManifestSchema() {
+    return manifestSchema;
+}
+export function validateManifest(candidate) {
+    const valid = validate(candidate);
+    if (valid) {
+        return { valid: true, errors: [], value: candidate };
+    }
+    return {
+        valid: false,
+        errors: formatErrors(validate.errors),
+        value: null
+    };
+}
+function formatErrors(errors) {
+    if (!errors || errors.length === 0) {
+        return ['Unknown validation error'];
+    }
+    return errors.map((error) => {
+        if (error.instancePath) {
+            return `${error.instancePath}: ${error.message ?? 'invalid value'}`;
+        }
+        if (error.schemaPath) {
+            return `${error.schemaPath}: ${error.message ?? 'invalid value'}`;
+        }
+        return error.message ?? 'invalid value';
+    });
+}
+export function resolveManifestSchemaPath(options = {}) {
+    if (!options.skipImports) {
+        const require = createRequire(import.meta.url);
+        try {
+            return require.resolve('#co/schema/manifest');
+        }
+        catch {
+            // fall through to fallback
+        }
+    }
+    return resolveManifestSchemaPathFallback(options.fromUrl ?? import.meta.url);
+}
+function resolveManifestSchemaPathFallback(fromUrl) {
+    let current = dirname(fileURLToPath(fromUrl));
+    while (current) {
+        const candidate = join(current, 'package.json');
+        if (existsSync(candidate)) {
+            return join(current, 'schemas', 'manifest.json');
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            current = null;
+            continue;
+        }
+        current = parent;
+    }
+    throw new Error('Unable to locate schemas/manifest.json');
+}
+function loadManifestSchema() {
+    const schemaPath = resolveManifestSchemaPath();
+    const raw = readFileSync(schemaPath, 'utf8');
+    return JSON.parse(raw);
+}

package/dist/packages/shared/manifest/writer.js

@@ -0,0 +1,2 @@
+export { sanitizeToolRunRecord, sanitizeToolRunEvent, mergeToolRunRecord, persistToolRunRecord } from './toolRuns.js';
+export { persistDesignManifest } from './designArtifacts.js';

package/dist/packages/shared/streams/stdio.js

@@ -0,0 +1,112 @@
+import { Buffer } from 'node:buffer';
+/**
+ * Creates a tracker that sequences stdout/stderr chunks while maintaining
+ * bounded in-memory buffers for each stream.
+ */
+export function createStdioTracker(options = {}) {
+    const encoding = options.encoding ?? 'utf-8';
+    const maxBufferBytes = options.maxBufferBytes ?? 64 * 1024;
+    const now = options.now ?? (() => new Date());
+    let sequence = Math.max(0, options.startSequence ?? 0);
+    const buffers = {
+        stdout: createInternalBuffer(),
+        stderr: createInternalBuffer()
+    };
+    const push = (stream, chunk) => {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, encoding);
+        const target = buffers[stream];
+        appendWithLimit(target, buffer, maxBufferBytes);
+        const chunkRecord = {
+            sequence: ++sequence,
+            stream,
+            bytes: buffer.byteLength,
+            data: buffer.toString(encoding),
+            timestamp: now().toISOString()
+        };
+        return chunkRecord;
+    };
+    const getBuffered = (stream) => {
+        const target = buffers[stream];
+        if (target.byteLength === 0) {
+            return '';
+        }
+        const activeChunks = snapshotChunks(target);
+        if (activeChunks.length === 0) {
+            return '';
+        }
+        if (activeChunks.length === 1) {
+            return activeChunks[0].toString(encoding);
+        }
+        return Buffer.concat(activeChunks, target.byteLength).toString(encoding);
+    };
+    const getBufferedBytes = (stream) => buffers[stream].byteLength;
+    const reset = () => {
+        buffers.stdout = createInternalBuffer();
+        buffers.stderr = createInternalBuffer();
+        sequence = Math.max(0, options.startSequence ?? 0);
+    };
+    return {
+        push,
+        getBuffered,
+        getBufferedBytes,
+        reset
+    };
+}
+function createInternalBuffer() {
+    return { chunks: [], start: 0, byteLength: 0 };
+}
+function snapshotChunks(buffer) {
+    if (buffer.start === 0) {
+        return buffer.chunks;
+    }
+    return buffer.chunks.slice(buffer.start);
+}
+function appendWithLimit(target, incoming, limit) {
+    if (limit <= 0) {
+        target.chunks = [];
+        target.start = 0;
+        target.byteLength = 0;
+        return;
+    }
+    if (!incoming || incoming.byteLength === 0) {
+        trimExcess(target, limit);
+        return;
+    }
+    if (incoming.byteLength >= limit) {
+        const trimmed = Buffer.from(incoming.subarray(incoming.byteLength - limit));
+        target.chunks = [trimmed];
+        target.start = 0;
+        target.byteLength = trimmed.byteLength;
+        return;
+    }
+    target.chunks.push(incoming);
+    target.byteLength += incoming.byteLength;
+    trimExcess(target, limit);
+}
+function trimExcess(target, limit) {
+    if (target.byteLength <= limit) {
+        return;
+    }
+    let startIndex = target.start;
+    const chunks = target.chunks;
+    while (target.byteLength > limit && startIndex < chunks.length) {
+        const head = chunks[startIndex];
+        if (!head) {
+            break;
+        }
+        const overflow = target.byteLength - limit;
+        if (head.byteLength <= overflow) {
+            target.byteLength -= head.byteLength;
+            startIndex += 1;
+            continue;
+        }
+        chunks[startIndex] = head.subarray(overflow);
+        target.byteLength -= overflow;
+        break;
+    }
+    target.start = startIndex;
+    if (target.start > 0 && target.start * 2 >= chunks.length) {
+        target.chunks = chunks.slice(target.start);
+        target.start = 0;
+    }
+}