@kbediako/codex-orchestrator 0.1.0

package/dist/scripts/design/pipeline/toolkit/common.js

@@ -0,0 +1,94 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function loadToolkitPermit(repoRoot) {
+    const permitPath = join(repoRoot, 'compliance', 'permit.json');
+    try {
+        const raw = await readFile(permitPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError?.code === 'ENOENT') {
+            console.warn('[design-toolkit] compliance/permit.json not found; proceeding without permit enforcement');
+            return { allowedSources: [] };
+        }
+        throw error;
+    }
+}
+export function ensureSourcePermitted(url, permit) {
+    const allowed = new Set((permit.allowedSources ?? [])
+        .map((entry) => {
+        try {
+            return new URL(entry.origin).origin;
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((origin) => Boolean(origin)));
+    const origin = new URL(url).origin;
+    if (allowed.size === 0 || allowed.has(origin)) {
+        return true;
+    }
+    console.warn(`[design-toolkit] Extraction target ${origin} is not listed in compliance/permit.json; continuing without permit match`);
+    return false;
+}
+export function resolveToolkitSources(pipeline, metadata) {
+    const sourceList = pipeline.sources.length > 0 ? pipeline.sources : buildSourcesFromCaptureUrls(metadata.captureUrls);
+    const breakpoints = pipeline.breakpoints.length > 0 ? pipeline.breakpoints : metadata.breakpoints;
+    const maskSelectors = pipeline.maskSelectors.length > 0 ? pipeline.maskSelectors : metadata.maskSelectors;
+    const finalBreakpoints = breakpoints.length > 0 ? breakpoints : defaultBreakpoints();
+    return sourceList.map((source, index) => ({
+        ...source,
+        referenceUrl: source.referenceUrl ?? source.url,
+        slug: source.slug ?? slugifyToolkitValue(source.id ?? source.url, index),
+        breakpoints: finalBreakpoints,
+        maskSelectors
+    }));
+}
+export function computeToolkitRetention(pipeline, fallback) {
+    if (pipeline.retention) {
+        return {
+            days: pipeline.retention.days,
+            autoPurge: pipeline.retention.autoPurge,
+            policy: pipeline.retention.policy ?? fallback.policy
+        };
+    }
+    return fallback;
+}
+export function buildRetentionMetadata(retention, now) {
+    const expiryMs = now.getTime() + Math.max(1, retention.days) * 24 * 60 * 60 * 1000;
+    return {
+        ...retention,
+        expiry: new Date(expiryMs).toISOString()
+    };
+}
+export function slugifyToolkitValue(value, index) {
+    const normalized = value
+        .toLowerCase()
+        .replace(/[^a-z0-9-_]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48);
+    if (normalized.length > 0) {
+        return normalized;
+    }
+    return `source-${index + 1}`;
+}
+function defaultBreakpoints() {
+    return [
+        {
+            id: 'desktop',
+            width: 1280,
+            height: 720
+        }
+    ];
+}
+function buildSourcesFromCaptureUrls(urls) {
+    return urls.map((url, index) => ({
+        id: `source-${index + 1}`,
+        url,
+        referenceUrl: url,
+        slug: slugifyToolkitValue(url, index),
+        title: null
+    }));
+}

package/dist/scripts/design/pipeline/toolkit/extract.js

@@ -0,0 +1,258 @@
+import { copyFile, mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { tmpdir } from 'node:os';
+import { loadDesignContext } from '../context.js';
+import { appendApprovals, appendToolkitArtifacts, ensureToolkitState, loadDesignRunState, saveDesignRunState, upsertStage, upsertToolkitContext } from '../state.js';
+import { stageArtifacts } from '../../../../orchestrator/src/persistence/ArtifactStager.js';
+import { buildRetentionMetadata, computeToolkitRetention, ensureSourcePermitted, loadToolkitPermit, resolveToolkitSources, slugifyToolkitValue } from './common.js';
+import { capturePageSnapshot } from './snapshot.js';
+async function main() {
+    const context = await loadDesignContext();
+    const state = await loadDesignRunState(context.statePath);
+    const stageId = 'design-toolkit-extract';
+    const toolkitState = ensureToolkitState(state);
+    const metadata = context.config.config.metadata.design;
+    const pipelineConfig = context.config.config.pipelines.hiFiDesignToolkit;
+    const sources = resolveToolkitSources(pipelineConfig, metadata);
+    if (sources.length === 0) {
+        upsertStage(state, {
+            id: stageId,
+            title: 'Toolkit context acquisition',
+            status: 'skipped',
+            notes: ['No hi-fi design toolkit sources configured.']
+        });
+        await saveDesignRunState(context.statePath, state);
+        console.log('[design-toolkit-extract] skipped — no sources configured');
+        return;
+    }
+    const permit = await loadToolkitPermit(context.repoRoot).catch((error) => {
+        console.warn('[design-toolkit-extract] permit load failed, proceeding without enforcement', error);
+        return { allowedSources: [] };
+    });
+    const fallbackRetention = {
+        days: state.retention?.days ?? metadata.retention.days,
+        autoPurge: state.retention?.autoPurge ?? metadata.retention.autoPurge,
+        policy: state.retention?.policy ?? 'design.config.retention'
+    };
+    toolkitState.retention = computeToolkitRetention(pipelineConfig, fallbackRetention);
+    const now = new Date();
+    const tmpRoot = join(tmpdir(), `design-toolkit-context-${Date.now()}`);
+    await mkdir(tmpRoot, { recursive: true });
+    let successCount = 0;
+    const failures = [];
+    const stagedArtifacts = [];
+    const approvals = [];
+    for (const source of sources) {
+        try {
+            ensureSourcePermitted(source.url, permit);
+            const contextResult = await stageContextArtifact({
+                context,
+                source,
+                tmpRoot,
+                retentionDays: toolkitState.retention?.days ?? fallbackRetention.days,
+                retentionPolicy: toolkitState.retention?.policy ?? fallbackRetention.policy,
+                autoPurge: toolkitState.retention?.autoPurge ?? fallbackRetention.autoPurge,
+                timestamp: now,
+                liveAssets: pipelineConfig.liveAssets,
+                interactionsEnabled: pipelineConfig.interactions?.enabled ?? false
+            });
+            successCount += 1;
+            stagedArtifacts.push(contextResult.artifact);
+            approvals.push({
+                id: `playwright-${source.slug}`,
+                actor: metadata.privacy.approver ?? 'design-reviewer',
+                reason: `Playwright extraction approved for ${source.url}`,
+                timestamp: new Date().toISOString()
+            });
+            upsertToolkitContext(state, {
+                id: source.id ?? slugifyToolkitValue(source.url, successCount - 1),
+                slug: source.slug,
+                title: source.title ?? null,
+                url: source.url,
+                referenceUrl: source.referenceUrl ?? source.url,
+                relativeDir: contextResult.artifact.relative_path.split('/').slice(0, -1).join('/'),
+                breakpoints: source.breakpoints.map((bp) => bp.id),
+                snapshotHtmlPath: contextResult.paths.inlineHtmlPath,
+                snapshotRawHtmlPath: contextResult.paths.rawHtmlPath,
+                snapshotCssPath: contextResult.paths.stylesPath,
+                palettePath: contextResult.paths.palettePath,
+                sectionsPath: contextResult.paths.sectionsPath,
+                palettePreview: contextResult.palettePreview,
+                fontFamilies: contextResult.fontFamilies,
+                runtimeCanvasColors: contextResult.runtimeCanvasColors,
+                resolvedFonts: contextResult.resolvedFonts,
+                interactionScriptPath: pipelineConfig.interactions?.scriptPath ?? null,
+                interactionWaitMs: pipelineConfig.interactions?.waitMs ?? null
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            failures.push(`${source.url}: ${message}`);
+            console.error(`[design-toolkit-extract] failed to process ${source.url}: ${message}`);
+        }
+    }
+    if (stagedArtifacts.length > 0) {
+        appendToolkitArtifacts(state, stagedArtifacts);
+    }
+    if (approvals.length > 0) {
+        appendApprovals(state, approvals);
+    }
+    const stageStatus = failures.length === 0 && successCount > 0 ? 'succeeded' : 'failed';
+    upsertStage(state, {
+        id: stageId,
+        title: 'Toolkit context acquisition',
+        status: stageStatus,
+        notes: failures.length > 0 ? failures : undefined,
+        metrics: {
+            source_count: sources.length,
+            captured_count: successCount
+        },
+        artifacts: stagedArtifacts.map((artifact) => ({
+            relative_path: artifact.relative_path,
+            stage: 'extract',
+            status: artifact.status,
+            description: artifact.description ?? undefined
+        }))
+    });
+    await saveDesignRunState(context.statePath, state);
+    if (stageStatus === 'failed') {
+        throw new Error('One or more toolkit sources failed staging.');
+    }
+    console.log(`[design-toolkit-extract] staged ${successCount} / ${sources.length} sources`);
+}
+async function stageContextArtifact(options) {
+    const { context, source, tmpRoot, retentionDays, retentionPolicy, autoPurge, timestamp, liveAssets, interactionsEnabled } = options;
+    const primaryBreakpoint = source.breakpoints[0];
+    const viewport = primaryBreakpoint
+        ? {
+            width: primaryBreakpoint.width,
+            height: primaryBreakpoint.height,
+            deviceScaleFactor: primaryBreakpoint.deviceScaleFactor
+        }
+        : undefined;
+    const snapshot = await capturePageSnapshot(source.url, {
+        keepScripts: liveAssets?.keepScripts ?? false,
+        maxStylesheets: liveAssets?.maxStylesheets ?? undefined,
+        mirrorAssets: liveAssets?.mirrorAssets ?? false,
+        allowRemoteAssets: liveAssets?.allowRemoteAssets ?? false,
+        viewport,
+        runInteractions: Boolean(interactionsEnabled)
+    });
+    const slugDir = join(tmpRoot, source.slug);
+    await mkdir(slugDir, { recursive: true });
+    const contextPayload = {
+        id: source.id,
+        url: source.url,
+        referenceUrl: source.referenceUrl,
+        breakpoints: source.breakpoints,
+        maskSelectors: source.maskSelectors,
+        capturedAt: timestamp.toISOString(),
+        colorPalettePreview: snapshot.colorPalette.slice(0, 12),
+        fontFamilies: snapshot.fontFamilies,
+        sectionCount: snapshot.sections.length,
+        runtimeCanvasColors: snapshot.runtimeCanvasColors,
+        resolvedFonts: snapshot.resolvedFonts
+    };
+    const contextPath = join(slugDir, 'context.json');
+    const inlineHtmlPath = join(slugDir, 'inline.html');
+    const rawHtmlPath = join(slugDir, 'original.html');
+    const stylesPath = join(slugDir, 'styles.css');
+    const palettePath = join(slugDir, 'palette.json');
+    const sectionsPath = join(slugDir, 'sections.json');
+    await Promise.all([
+        writeFile(contextPath, `${JSON.stringify(contextPayload, null, 2)}\n`, 'utf8'),
+        writeFile(inlineHtmlPath, snapshot.inlineHtml, 'utf8'),
+        writeFile(rawHtmlPath, snapshot.originalHtml, 'utf8'),
+        writeFile(stylesPath, snapshot.aggregatedCss, 'utf8'),
+        writeFile(palettePath, `${JSON.stringify(snapshot.colorPalette, null, 2)}\n`, 'utf8'),
+        writeFile(sectionsPath, `${JSON.stringify(snapshot.sections, null, 2)}\n`, 'utf8')
+    ]);
+    if (snapshot.assets.length > 0) {
+        for (const asset of snapshot.assets) {
+            const assetPath = join(slugDir, asset.relativePath);
+            await mkdir(dirname(assetPath), { recursive: true });
+            await writeFile(assetPath, asset.buffer);
+        }
+    }
+    const stagedFiles = await stageArtifacts({
+        taskId: context.taskId,
+        runId: context.runId,
+        artifacts: [
+            {
+                path: relative(process.cwd(), contextPath),
+                description: `Toolkit context for ${source.url}`
+            },
+            {
+                path: relative(process.cwd(), inlineHtmlPath),
+                description: `Inlined Cognition clone for ${source.url}`
+            },
+            {
+                path: relative(process.cwd(), rawHtmlPath),
+                description: `Original HTML for ${source.url}`
+            },
+            {
+                path: relative(process.cwd(), stylesPath),
+                description: `Aggregated CSS for ${source.url}`
+            },
+            {
+                path: relative(process.cwd(), palettePath),
+                description: `Color palette for ${source.url}`
+            },
+            {
+                path: relative(process.cwd(), sectionsPath),
+                description: `Section summaries for ${source.url}`
+            }
+        ],
+        options: {
+            relativeDir: join('design-toolkit', 'context', source.slug),
+            overwrite: true
+        }
+    });
+    const [contextRecord, inlineRecord, rawRecord, stylesRecord, paletteRecord, sectionsRecord] = stagedFiles;
+    const contextDir = join(process.cwd(), dirname(contextRecord.path));
+    if (snapshot.assets.length > 0) {
+        for (const asset of snapshot.assets) {
+            const tempPath = join(slugDir, asset.relativePath);
+            const destinationPath = join(contextDir, asset.relativePath);
+            await mkdir(dirname(destinationPath), { recursive: true });
+            await copyFile(tempPath, destinationPath);
+        }
+    }
+    const retention = buildRetentionMetadata({
+        days: retentionDays,
+        autoPurge,
+        policy: retentionPolicy
+    }, timestamp);
+    return {
+        artifact: {
+            id: source.id,
+            stage: 'extract',
+            status: 'succeeded',
+            relative_path: contextRecord.path,
+            description: `Context snapshot for ${source.slug}`,
+            retention,
+            metrics: {
+                breakpoint_count: source.breakpoints.length,
+                color_count: snapshot.colorPalette.length,
+                section_count: snapshot.sections.length
+            }
+        },
+        paths: {
+            contextPath: contextRecord.path,
+            inlineHtmlPath: inlineRecord.path,
+            rawHtmlPath: rawRecord.path,
+            stylesPath: stylesRecord.path,
+            palettePath: paletteRecord.path,
+            sectionsPath: sectionsRecord.path
+        },
+        palettePreview: snapshot.colorPalette.slice(0, 12),
+        fontFamilies: snapshot.fontFamilies,
+        runtimeCanvasColors: snapshot.runtimeCanvasColors,
+        resolvedFonts: snapshot.resolvedFonts
+    };
+}
+main().catch((error) => {
+    console.error('[design-toolkit-extract] failed to stage toolkit context');
+    console.error(error instanceof Error ? error.stack ?? error.message : error);
+    process.exitCode = 1;
+});

package/dist/scripts/design/pipeline/toolkit/publish.js

@@ -0,0 +1,202 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawn } from 'node:child_process';
+import { loadDesignContext } from '../context.js';
+import { appendToolkitArtifacts, ensureToolkitState, loadDesignRunState, saveDesignRunState, upsertStage } from '../state.js';
+import { stageArtifacts } from '../../../../orchestrator/src/persistence/ArtifactStager.js';
+import { buildRetentionMetadata } from './common.js';
+import { resolveToolkitPublishActions } from './publishActions.js';
+const DESIGN_SYSTEM_DIR = 'packages/design-system';
+async function main() {
+    const context = await loadDesignContext();
+    const state = await loadDesignRunState(context.statePath);
+    const stageId = 'design-toolkit-publish';
+    const toolkitState = ensureToolkitState(state);
+    const contexts = toolkitState.contexts.filter((entry) => entry.tokensPath);
+    const pipelineConfig = context.config.config.pipelines.hiFiDesignToolkit;
+    const publishActions = resolveToolkitPublishActions(pipelineConfig);
+    const hasAnyAction = publishActions.updateTokens || publishActions.updateComponents || publishActions.runVisualRegression;
+    if ((publishActions.updateTokens || publishActions.updateComponents) && contexts.length === 0) {
+        upsertStage(state, {
+            id: stageId,
+            title: 'Toolkit publish + design-system integration',
+            status: 'skipped',
+            notes: ['No token artifacts available. Run earlier stages first.']
+        });
+        await saveDesignRunState(context.statePath, state);
+        console.log('[design-toolkit-publish] skipped — no token artifacts');
+        return;
+    }
+    if (!hasAnyAction) {
+        upsertStage(state, {
+            id: stageId,
+            title: 'Toolkit publish + design-system integration',
+            status: 'skipped',
+            notes: ['publish.update_* config disabled all publish actions.']
+        });
+        await saveDesignRunState(context.statePath, state);
+        console.log('[design-toolkit-publish] skipped — publish actions disabled via config');
+        return;
+    }
+    const retention = toolkitState.retention ?? {
+        days: state.retention?.days ?? 30,
+        autoPurge: state.retention?.autoPurge ?? false,
+        policy: state.retention?.policy ?? 'design.config.retention'
+    };
+    const repoRoot = context.repoRoot;
+    const tokensTarget = join(repoRoot, DESIGN_SYSTEM_DIR, 'tokens', 'src', 'hi-fi');
+    const componentTarget = join(repoRoot, DESIGN_SYSTEM_DIR, 'src', 'components', 'hi-fi');
+    const dirPromises = [];
+    if (publishActions.updateTokens) {
+        dirPromises.push(mkdir(tokensTarget, { recursive: true }).then(() => undefined));
+    }
+    if (publishActions.updateComponents) {
+        dirPromises.push(mkdir(componentTarget, { recursive: true }).then(() => undefined));
+    }
+    await Promise.all(dirPromises);
+    let tokensWritten = 0;
+    let componentsWritten = 0;
+    if (publishActions.updateTokens || publishActions.updateComponents) {
+        for (const entry of contexts) {
+            const sourcePath = join(repoRoot, entry.tokensPath);
+            if (publishActions.updateTokens) {
+                const destPath = join(tokensTarget, `${entry.slug}.json`);
+                const tokensRaw = await readFile(sourcePath, 'utf8');
+                const tokens = JSON.parse(tokensRaw);
+                tokens.metadata = {
+                    ...(tokens.metadata ?? {}),
+                    manifest: context.manifestPath
+                };
+                await writeFile(destPath, `${JSON.stringify(tokens, null, 2)}\n`, 'utf8');
+                tokensWritten += 1;
+            }
+            if (publishActions.updateComponents) {
+                const componentDir = join(componentTarget, entry.slug);
+                await mkdir(componentDir, { recursive: true });
+                const componentName = toPascalCase(entry.slug);
+                const componentFile = join(componentDir, 'index.ts');
+                const componentSource = `export const ${componentName} = {\n  id: '${entry.slug}',\n  tokensFile: '../../tokens/src/hi-fi/${entry.slug}.json',\n  referencePath: '${entry.referencePath ?? ''}'\n};\n`;
+                await writeFile(componentFile, componentSource, 'utf8');
+                componentsWritten += 1;
+            }
+        }
+    }
+    const commandResults = await runDesignSystemCommands(repoRoot, publishActions);
+    const tmpRoot = join(tmpdir(), `design-toolkit-publish-${Date.now()}`);
+    await mkdir(tmpRoot, { recursive: true });
+    const logPath = join(tmpRoot, 'publish-summary.json');
+    await writeFile(logPath, JSON.stringify(commandResults, null, 2), 'utf8');
+    const [stagedLog] = await stageArtifacts({
+        taskId: context.taskId,
+        runId: context.runId,
+        artifacts: [
+            {
+                path: relative(process.cwd(), logPath),
+                description: 'Design-system publish logs'
+            }
+        ],
+        options: {
+            relativeDir: 'design-toolkit/publish/logs',
+            overwrite: true
+        }
+    });
+    const retentionMetadata = buildRetentionMetadata(retention, new Date());
+    const artifact = {
+        id: 'design-system-publish',
+        stage: 'publish',
+        status: commandResults.failed === 0 ? 'succeeded' : 'failed',
+        relative_path: stagedLog.path,
+        description: 'Design-system integration summary',
+        retention: retentionMetadata,
+        metrics: {
+            contexts_updated: Math.max(tokensWritten, componentsWritten),
+            tokens_written: tokensWritten,
+            components_written: componentsWritten,
+            commands_passed: commandResults.passed,
+            commands_failed: commandResults.failed,
+            commands_executed: commandResults.executed.length
+        }
+    };
+    appendToolkitArtifacts(state, [artifact]);
+    const stageNotes = [];
+    if (!publishActions.updateTokens) {
+        stageNotes.push('Token publishing disabled via config.');
+    }
+    if (!publishActions.updateComponents) {
+        stageNotes.push('Component publishing disabled via config.');
+    }
+    if (!publishActions.runVisualRegression) {
+        stageNotes.push('Visual regression command disabled via config.');
+    }
+    upsertStage(state, {
+        id: stageId,
+        title: 'Toolkit publish + design-system integration',
+        status: artifact.status === 'succeeded' ? 'succeeded' : 'failed',
+        notes: commandResults.failed > 0
+            ? [...stageNotes, ...commandResults.errors]
+            : stageNotes.length > 0
+                ? stageNotes
+                : undefined,
+        metrics: artifact.metrics ?? undefined,
+        artifacts: [
+            {
+                relative_path: stagedLog.path,
+                stage: 'publish',
+                status: artifact.status,
+                description: 'publish-summary.json'
+            }
+        ]
+    });
+    await saveDesignRunState(context.statePath, state);
+    if (artifact.status === 'failed') {
+        throw new Error('One or more design-system commands failed.');
+    }
+    console.log('[design-toolkit-publish] updated design-system tokens/components');
+}
+async function runDesignSystemCommands(repoRoot, actions) {
+    const commands = [];
+    if (actions.updateTokens) {
+        commands.push({ args: ['npm', '--prefix', DESIGN_SYSTEM_DIR, 'run', 'build:tokens'], label: 'build:tokens' });
+    }
+    if (actions.updateComponents) {
+        commands.push({ args: ['npm', '--prefix', DESIGN_SYSTEM_DIR, 'run', 'lint'], label: 'lint' });
+    }
+    if (actions.runVisualRegression) {
+        commands.push({ args: ['npm', '--prefix', DESIGN_SYSTEM_DIR, 'run', 'test:visual'], label: 'test:visual' });
+    }
+    const errors = [];
+    const executed = [];
+    let passed = 0;
+    let failed = 0;
+    for (const command of commands) {
+        const exitCode = await spawnCommand(command.args, repoRoot);
+        executed.push(command.label);
+        if (exitCode === 0) {
+            passed += 1;
+        }
+        else {
+            failed += 1;
+            errors.push(`${command.label} failed with exit code ${exitCode}`);
+        }
+    }
+    return { passed, failed, errors, executed };
+}
+function spawnCommand(args, cwd) {
+    return new Promise((resolve) => {
+        const child = spawn(args[0], args.slice(1), { stdio: 'inherit', cwd });
+        child.on('close', (code) => resolve(code ?? 1));
+        child.on('error', () => resolve(1));
+    });
+}
+function toPascalCase(value) {
+    return value
+        .split(/[-_\s]+/)
+        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join('');
+}
+main().catch((error) => {
+    console.error('[design-toolkit-publish] failed to publish toolkit outputs');
+    console.error(error instanceof Error ? error.stack ?? error.message : error);
+    process.exitCode = 1;
+});

package/dist/scripts/design/pipeline/toolkit/publishActions.js

@@ -0,0 +1,12 @@
+export function resolveToolkitPublishActions(pipeline) {
+    const publish = pipeline.publish ?? {
+        updateTokens: true,
+        updateComponents: true,
+        runVisualRegression: true
+    };
+    return {
+        updateTokens: publish.updateTokens !== false,
+        updateComponents: publish.updateComponents !== false,
+        runVisualRegression: publish.runVisualRegression !== false
+    };
+}