@pennyfarthing/core 10.4.0 → 11.0.0

package/packages/core/dist/shared/migrate-theme-schema.test.js

@@ -0,0 +1,100 @@
+/**
+ * Theme Schema Migration Tests - MSSCI-12478
+ *
+ * Tests for the migration script that consolidates quote into catchphrases.
+ * RED STATE: These tests should FAIL until implementation is complete.
+ */
+import { describe, it, before } from 'node:test';
+import assert from 'node:assert';
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { discoverAllThemeDirs } from './theme-loader.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+describe('MSSCI-12478: Theme YAML Migration', () => {
+    let allThemeFiles;
+    before(() => {
+        // Discover all theme directories (core + theme packages + custom)
+        const themeDirs = discoverAllThemeDirs();
+        const seen = new Set();
+        allThemeFiles = [];
+        for (const dir of themeDirs) {
+            if (!existsSync(dir))
+                continue;
+            const files = readdirSync(dir).filter(f => f.endsWith('.yaml'));
+            for (const file of files) {
+                if (!seen.has(file)) {
+                    seen.add(file);
+                    allThemeFiles.push({ file, dir });
+                }
+            }
+        }
+    });
+    describe('AC2: All themes updated', () => {
+        it('should have themes across all discovered sources', () => {
+            assert.ok(allThemeFiles.length > 0, 'Should discover at least one theme');
+        });
+        it('no theme file should contain quote: field under agents', () => {
+            const themesWithQuote = [];
+            for (const { file, dir } of allThemeFiles) {
+                const content = readFileSync(join(dir, file), 'utf-8');
+                // Check for quote: at 4-space indent (under agent definition)
+                if (/^ {4}quote:/m.test(content)) {
+                    themesWithQuote.push(file);
+                }
+            }
+            assert.strictEqual(themesWithQuote.length, 0, `These themes still have quote field: ${themesWithQuote.slice(0, 5).join(', ')}${themesWithQuote.length > 5 ? ` and ${themesWithQuote.length - 5} more` : ''}`);
+        });
+        it('every theme should have catchphrases array for each agent', () => {
+            const themesWithMissingCatchphrases = [];
+            for (const { file, dir } of allThemeFiles) {
+                // Skip control.yaml which is a special baseline theme
+                if (file === 'control.yaml')
+                    continue;
+                const content = readFileSync(join(dir, file), 'utf-8');
+                // Count catchphrases section markers (10 agents expected)
+                const catchphrasesMatches = content.match(/^ {4}catchphrases:/gm);
+                if (!catchphrasesMatches || catchphrasesMatches.length < 10) {
+                    themesWithMissingCatchphrases.push(file);
+                }
+            }
+            assert.strictEqual(themesWithMissingCatchphrases.length, 0, `These themes have missing catchphrases: ${themesWithMissingCatchphrases.slice(0, 5).join(', ')}${themesWithMissingCatchphrases.length > 5 ? ` and ${themesWithMissingCatchphrases.length - 5} more` : ''}`);
+        });
+    });
+    describe('AC1: Migration preserves original quote in catchphrases', () => {
+        // These tests use resolveThemePath so they work regardless of which package
+        // the theme lives in.
+        it('the-expanse orchestrator catchphrases should contain original quote', () => {
+            const themeDirs = discoverAllThemeDirs();
+            let content = null;
+            for (const dir of themeDirs) {
+                const p = join(dir, 'the-expanse.yaml');
+                if (existsSync(p)) {
+                    content = readFileSync(p, 'utf-8');
+                    break;
+                }
+            }
+            assert.ok(content, 'the-expanse.yaml should be discoverable');
+            // Original quote was: "Doors and corners, kid. That's where they get you."
+            // This should now be in the catchphrases array
+            assert.ok(content.includes("Doors and corners, kid. That's where they get you."), 'Quote should still be present in file');
+            assert.ok(/catchphrases:[\s\S]*?Doors and corners/.test(content), 'Quote should be within catchphrases array, not as separate quote field');
+        });
+        it('star-trek-tng picard catchphrases should contain original quote', () => {
+            const themeDirs = discoverAllThemeDirs();
+            let content = null;
+            for (const dir of themeDirs) {
+                const p = join(dir, 'star-trek-tng.yaml');
+                if (existsSync(p)) {
+                    content = readFileSync(p, 'utf-8');
+                    break;
+                }
+            }
+            assert.ok(content, 'star-trek-tng.yaml should be discoverable');
+            // Picard's famous quote should be in catchphrases
+            assert.ok(/catchphrases:[\s\S]*?(Make it so|Engage)/.test(content), 'Picard quote should be within catchphrases array');
+        });
+    });
+});
+//# sourceMappingURL=migrate-theme-schema.test.js.map

package/packages/core/dist/shared/migrate-theme-schema.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-theme-schema.test.js","sourceRoot":"","sources":["../../src/shared/migrate-theme-schema.test.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/shared/portrait-resolver.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Portrait Resolver - Smart path resolution for Pennyfarthing portraits
+ *
+ * Checks paths in priority order:
+ * 1. PENNYFARTHING_DIST env var (explicit override)
+ * 2. Monorepo root (pennyfarthing-dist/ at repo root for dogfooding)
+ * 3. Sibling directory (for dev scenarios)
+ * 4. Scoped npm (node_modules/@pennyfarthing/core/pennyfarthing-dist/)
+ * 5. Legacy npm (node_modules/pennyfarthing/pennyfarthing-dist/)
+ */
+export interface PortraitPaths {
+    portraitsDir: string;
+    themesDir: string;
+    agentsDir: string;
+}
+/**
+ * Resolve the pennyfarthing-dist directory path
+ * Checks multiple locations in priority order
+ */
+export declare function resolvePennyfarthingDist(): string | null;
+/**
+ * Resolve the full path to a portrait image.
+ * Looks up shortName + OCEAN from theme YAML to construct the portrait slug,
+ * then searches core and theme package portrait directories.
+ *
+ * @param theme - Theme name (e.g., 'monty-python', 'mash')
+ * @param agent - Agent role (e.g., 'sm', 'tea', 'dev')
+ * @returns Full path to portrait file, or null if not found
+ */
+export declare function resolvePortraitPath(theme: string, agent: string): string | null;
+/**
+ * Get all portrait-related paths for a resolved dist directory
+ */
+export declare function getPortraitPaths(distPath: string): PortraitPaths;
+//# sourceMappingURL=portrait-resolver.d.ts.map

package/packages/core/dist/shared/portrait-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portrait-resolver.d.ts","sourceRoot":"","sources":["../../src/shared/portrait-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAgDxD;AA2ID;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkC/E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAShE"}

package/packages/core/dist/shared/portrait-resolver.js

@@ -0,0 +1,259 @@
+/**
+ * Portrait Resolver - Smart path resolution for Pennyfarthing portraits
+ *
+ * Checks paths in priority order:
+ * 1. PENNYFARTHING_DIST env var (explicit override)
+ * 2. Monorepo root (pennyfarthing-dist/ at repo root for dogfooding)
+ * 3. Sibling directory (for dev scenarios)
+ * 4. Scoped npm (node_modules/@pennyfarthing/core/pennyfarthing-dist/)
+ * 5. Legacy npm (node_modules/pennyfarthing/pennyfarthing-dist/)
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+// Get the directory where this module is located
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Resolve the pennyfarthing-dist directory path
+ * Checks multiple locations in priority order
+ */
+export function resolvePennyfarthingDist() {
+    // 1. PENNYFARTHING_DIST env var (explicit override)
+    const envPath = process.env.PENNYFARTHING_DIST;
+    if (envPath) {
+        if (existsSync(envPath)) {
+            return envPath;
+        }
+        // Env var set but path doesn't exist - fall through to other checks
+    }
+    // 2. Monorepo root (pennyfarthing-dist/ at repo root for dogfooding)
+    // Walk up from current directory looking for pennyfarthing-dist/
+    let currentDir = __dirname;
+    for (let i = 0; i < 10; i++) {
+        const monorepoPath = join(currentDir, 'pennyfarthing-dist');
+        if (existsSync(monorepoPath)) {
+            return monorepoPath;
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir)
+            break; // Reached root
+        currentDir = parentDir;
+    }
+    // 3. Sibling directory (for dev scenarios)
+    // Check ../pennyfarthing-dist, ../../pennyfarthing-dist from module location
+    currentDir = __dirname;
+    for (let i = 0; i < 5; i++) {
+        currentDir = dirname(currentDir);
+        const siblingPath = join(currentDir, 'pennyfarthing-dist');
+        if (existsSync(siblingPath)) {
+            return siblingPath;
+        }
+    }
+    // 4. Scoped npm (node_modules/@pennyfarthing/core/pennyfarthing-dist/)
+    const scopedNpmPath = resolve(__dirname, '..', '..', '..', '@pennyfarthing', 'core', 'pennyfarthing-dist');
+    if (existsSync(scopedNpmPath)) {
+        return scopedNpmPath;
+    }
+    // 5. Legacy npm (node_modules/pennyfarthing/pennyfarthing-dist/)
+    const legacyNpmPath = resolve(__dirname, '..', '..', '..', 'pennyfarthing', 'pennyfarthing-dist');
+    if (existsSync(legacyNpmPath)) {
+        return legacyNpmPath;
+    }
+    // No valid path found
+    return null;
+}
+/**
+ * Convert a name to URL-safe slug (lowercase kebab-case).
+ */
+function toSlug(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+/**
+ * Extract portrait slug ({shortName}-{OCEAN}) for an agent from a theme YAML file.
+ * Inlined here to avoid circular dependency with theme-loader.ts.
+ */
+function extractAgentSlug(themeYamlPath, agent) {
+    if (!existsSync(themeYamlPath))
+        return null;
+    try {
+        const content = readFileSync(themeYamlPath, 'utf-8');
+        const parsed = parseYaml(content);
+        const agentData = parsed?.agents?.[agent];
+        if (!agentData)
+            return null;
+        const shortName = agentData.shortName || agentData.character?.split(' ')[0];
+        const ocean = agentData.ocean;
+        if (shortName && ocean?.O != null && ocean?.C != null && ocean?.E != null && ocean?.A != null && ocean?.N != null) {
+            return `${toSlug(shortName)}-${ocean.O}${ocean.C}${ocean.E}${ocean.A}${ocean.N}`;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find portrait in a specific theme directory.
+ * Matches by slug (shortName-OCEAN) derived from theme YAML, falling back to agent name prefix.
+ */
+function findPortraitInDir(portraitsThemeDir, slug) {
+    if (!existsSync(portraitsThemeDir)) {
+        return null;
+    }
+    try {
+        // Check size subdirectories in preference order
+        const sizeDirectories = ['large', 'medium', 'small', 'original'];
+        let files = [];
+        let searchDir = portraitsThemeDir;
+        for (const sizeDir of sizeDirectories) {
+            const sizedPath = join(portraitsThemeDir, sizeDir);
+            if (existsSync(sizedPath)) {
+                files = readdirSync(sizedPath);
+                searchDir = sizedPath;
+                break;
+            }
+        }
+        // Fallback to root directory if no size subdirectories
+        if (files.length === 0) {
+            files = readdirSync(portraitsThemeDir);
+            searchDir = portraitsThemeDir;
+        }
+        // Match by slug prefix (e.g., "announcer-44441" matches "announcer-44441.png")
+        for (const file of files) {
+            if (file.toLowerCase().startsWith(slug.toLowerCase()) &&
+                (file.endsWith('.png') || file.endsWith('.jpg'))) {
+                return join(searchDir, file);
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * Discover theme package portrait directories.
+ * Inlined here to avoid circular dependency with theme-loader.ts.
+ */
+function discoverThemePackagePortraitDirs() {
+    const results = [];
+    let currentDir = process.cwd();
+    // Check node_modules/@pennyfarthing/themes-*
+    for (let i = 0; i < 10; i++) {
+        const nmPfDir = join(currentDir, 'node_modules', '@pennyfarthing');
+        if (existsSync(nmPfDir)) {
+            try {
+                for (const entry of readdirSync(nmPfDir)) {
+                    if (!entry.startsWith('themes-'))
+                        continue;
+                    const pkgJsonPath = join(nmPfDir, entry, 'package.json');
+                    if (!existsSync(pkgJsonPath))
+                        continue;
+                    try {
+                        const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+                        if (pkgJson['pennyfarthing-theme-pack'] === true) {
+                            results.push({ portraitsDir: join(nmPfDir, entry, 'portraits') });
+                        }
+                    }
+                    catch { /* skip */ }
+                }
+            }
+            catch { /* skip */ }
+            break;
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir)
+            break;
+        currentDir = parentDir;
+    }
+    // Check monorepo packages/themes-*
+    currentDir = process.cwd();
+    for (let i = 0; i < 10; i++) {
+        const packagesDir = join(currentDir, 'packages');
+        if (existsSync(packagesDir)) {
+            try {
+                for (const entry of readdirSync(packagesDir)) {
+                    if (!entry.startsWith('themes-'))
+                        continue;
+                    const pkgJsonPath = join(packagesDir, entry, 'package.json');
+                    if (!existsSync(pkgJsonPath))
+                        continue;
+                    try {
+                        const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+                        if (pkgJson['pennyfarthing-theme-pack'] === true) {
+                            const portraitsDir = join(packagesDir, entry, 'portraits');
+                            if (!results.some(r => r.portraitsDir === portraitsDir)) {
+                                results.push({ portraitsDir });
+                            }
+                        }
+                    }
+                    catch { /* skip */ }
+                }
+            }
+            catch { /* skip */ }
+            break;
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir)
+            break;
+        currentDir = parentDir;
+    }
+    return results;
+}
+/**
+ * Resolve the full path to a portrait image.
+ * Looks up shortName + OCEAN from theme YAML to construct the portrait slug,
+ * then searches core and theme package portrait directories.
+ *
+ * @param theme - Theme name (e.g., 'monty-python', 'mash')
+ * @param agent - Agent role (e.g., 'sm', 'tea', 'dev')
+ * @returns Full path to portrait file, or null if not found
+ */
+export function resolvePortraitPath(theme, agent) {
+    const distPath = resolvePennyfarthingDist();
+    const themePackages = discoverThemePackagePortraitDirs();
+    // Resolve slug from theme YAML — check core then packages
+    let slug = null;
+    if (distPath) {
+        slug = extractAgentSlug(join(distPath, 'personas', 'themes', `${theme}.yaml`), agent);
+    }
+    if (!slug) {
+        for (const pkg of themePackages) {
+            const themesDir = join(dirname(pkg.portraitsDir), 'themes');
+            slug = extractAgentSlug(join(themesDir, `${theme}.yaml`), agent);
+            if (slug)
+                break;
+        }
+    }
+    // Fall back to agent role name if theme YAML doesn't have shortName/OCEAN
+    const searchSlug = slug || agent;
+    // 1. Check core portraits
+    if (distPath) {
+        const paths = getPortraitPaths(distPath);
+        const coreResult = findPortraitInDir(join(paths.portraitsDir, theme), searchSlug);
+        if (coreResult)
+            return coreResult;
+    }
+    // 2. Check theme package portraits
+    for (const pkg of themePackages) {
+        const pkgResult = findPortraitInDir(join(pkg.portraitsDir, theme), searchSlug);
+        if (pkgResult)
+            return pkgResult;
+    }
+    return null;
+}
+/**
+ * Get all portrait-related paths for a resolved dist directory
+ */
+export function getPortraitPaths(distPath) {
+    // Normalize path to remove trailing slashes
+    const normalizedPath = distPath.replace(/\/+$/, '');
+    return {
+        portraitsDir: join(normalizedPath, 'personas', 'portraits'),
+        themesDir: join(normalizedPath, 'personas'),
+        agentsDir: join(normalizedPath, 'agents'),
+    };
+}
+//# sourceMappingURL=portrait-resolver.js.map

package/packages/core/dist/shared/portrait-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portrait-resolver.js","sourceRoot":"","sources":["../../src/shared/portrait-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAQ1C,iDAAiD;AACjD,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC;;;GAGG;AACH,MAAM,UAAU,wBAAwB;IACtC,oDAAoD;IACpD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAC/C,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACxB,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,oEAAoE;IACtE,CAAC;IAED,qEAAqE;IACrE,iEAAiE;IACjE,IAAI,UAAU,GAAG,SAAS,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,EAAE,oBAAoB,CAAC,CAAC;QAC5D,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7B,OAAO,YAAY,CAAC;QACtB,CAAC;QACD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QACtC,IAAI,SAAS,KAAK,UAAU;YAAE,MAAM,CAAC,eAAe;QACpD,UAAU,GAAG,SAAS,CAAC;IACzB,CAAC;IAED,2CAA2C;IAC3C,6EAA6E;IAC7E,UAAU,GAAG,SAAS,CAAC;IACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QACjC,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,oBAAoB,CAAC,CAAC;QAC3D,IAAI,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YAC5B,OAAO,WAAW,CAAC;QACrB,CAAC;IACH,CAAC;IAED,uEAAuE;IACvE,MAAM,aAAa,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC3G,IAAI,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAC9B,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,iEAAiE;IACjE,MAAM,aAAa,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,oBAAoB,CAAC,CAAC;IAClG,IAAI,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAC9B,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,sBAAsB;IACtB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,SAAS,MAAM,CAAC,IAAY;IAC1B,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,aAAqB,EAAE,KAAa;IAC5D,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QACrD,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAA+I,CAAC;QAChL,MAAM,SAAS,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC;QAE5B,MAAM,SAAS,GAAG,SAAS,CAAC,SAAS,IAAI,SAAS,CAAC,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5E,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC;QAC9B,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;YAClH,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;QACnF,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CAAC,iBAAyB,EAAE,IAAY;IAChE,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,gDAAgD;QAChD,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;QACjE,IAAI,KAAK,GAAa,EAAE,CAAC;QACzB,IAAI,SAAS,GAAG,iBAAiB,CAAC;QAElC,KAAK,MAAM,OAAO,IAAI,eAAe,EAAE,CAAC;YACtC,MAAM,SAAS,GAAG,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;YACnD,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC1B,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;gBAC/B,SAAS,GAAG,SAAS,CAAC;gBACtB,MAAM;YACR,CAAC;QACH,CAAC;QAED,uDAAuD;QACvD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,KAAK,GAAG,WAAW,CAAC,iBAAiB,CAAC,CAAC;YACvC,SAAS,GAAG,iBAAiB,CAAC;QAChC,CAAC;QAED,+EAA+E;QAC/E,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjD,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;gBACrD,OAAO,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,SAAS,gCAAgC;IACvC,MAAM,OAAO,GAAoC,EAAE,CAAC;IACpD,IAAI,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAE/B,6CAA6C;IAC7C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,cAAc,EAAE,gBAAgB,CAAC,CAAC;QACnE,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC;gBACH,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;oBACzC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC;wBAAE,SAAS;oBAC3C,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;oBACzD,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;wBAAE,SAAS;oBACvC,IAAI,CAAC;wBACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;wBAC/D,IAAI,OAAO,CAAC,0BAA0B,CAAC,KAAK,IAAI,EAAE,CAAC;4BACjD,OAAO,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC;wBACpE,CAAC;oBACH,CAAC;oBAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC;gBACxB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC;YACtB,MAAM;QACR,CAAC;QACD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QACtC,IAAI,SAAS,KAAK,UAAU;YAAE,MAAM;QACpC,UAAU,GAAG,SAAS,CAAC;IACzB,CAAC;IAED,mCAAmC;IACnC,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QACjD,IAAI,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;oBAC7C,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC;wBAAE,SAAS;oBAC3C,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;oBAC7D,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;wBAAE,SAAS;oBACvC,IAAI,CAAC;wBACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;wBAC/D,IAAI,OAAO,CAAC,0BAA0B,CAAC,KAAK,IAAI,EAAE,CAAC;4BACjD,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;4BAC3D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,YAAY,CAAC,EAAE,CAAC;gCACxD,OAAO,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC;4BACjC,CAAC;wBACH,CAAC;oBACH,CAAC;oBAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC;gBACxB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC;YACtB,MAAM;QACR,CAAC;QACD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QACtC,IAAI,SAAS,KAAK,UAAU;YAAE,MAAM;QACpC,UAAU,GAAG,SAAS,CAAC;IACzB,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,KAAa;IAC9D,MAAM,QAAQ,GAAG,wBAAwB,EAAE,CAAC;IAC5C,MAAM,aAAa,GAAG,gCAAgC,EAAE,CAAC;IAEzD,0DAA0D;IAC1D,IAAI,IAAI,GAAkB,IAAI,CAAC;IAC/B,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,KAAK,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC;IACxF,CAAC;IACD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;YAChC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,CAAC;YAC5D,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,KAAK,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC;YACjE,IAAI,IAAI;gBAAE,MAAM;QAClB,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,MAAM,UAAU,GAAG,IAAI,IAAI,KAAK,CAAC;IAEjC,0BAA0B;IAC1B,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QACzC,MAAM,UAAU,GAAG,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,EAAE,UAAU,CAAC,CAAC;QAClF,IAAI,UAAU;YAAE,OAAO,UAAU,CAAC;IACpC,CAAC;IAED,mCAAmC;IACnC,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;QAChC,MAAM,SAAS,GAAG,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,EAAE,UAAU,CAAC,CAAC;QAC/E,IAAI,SAAS;YAAE,OAAO,SAAS,CAAC;IAClC,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,4CAA4C;IAC5C,MAAM,cAAc,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAEpD,OAAO;QACL,YAAY,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,EAAE,WAAW,CAAC;QAC3D,SAAS,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC;QAC3C,SAAS,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC;KAC1C,CAAC;AACJ,CAAC"}

package/packages/core/dist/shared/portrait-resolver.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=portrait-resolver.test.d.ts.map

package/packages/core/dist/shared/portrait-resolver.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portrait-resolver.test.d.ts","sourceRoot":"","sources":["../../src/shared/portrait-resolver.test.ts"],"names":[],"mappings":""}

package/packages/core/dist/shared/portrait-resolver.test.js

@@ -0,0 +1,157 @@
+import { describe, it, afterEach } from 'node:test';
+import assert from 'node:assert';
+import path from 'node:path';
+import { resolvePennyfarthingDist, resolvePortraitPath, getPortraitPaths, } from './portrait-resolver.js';
+describe('portrait-resolver', () => {
+    describe('resolvePennyfarthingDist', () => {
+        const originalEnv = process.env.PENNYFARTHING_DIST;
+        afterEach(() => {
+            // Restore original env
+            if (originalEnv !== undefined) {
+                process.env.PENNYFARTHING_DIST = originalEnv;
+            }
+            else {
+                delete process.env.PENNYFARTHING_DIST;
+            }
+        });
+        it('should return PENNYFARTHING_DIST env var when set and path exists', () => {
+            // Scenario 1: Explicit env var override with existing path
+            // Use the actual pennyfarthing-dist path that exists
+            const actualDistPath = resolvePennyfarthingDist();
+            assert.ok(actualDistPath !== null, 'Should have a valid dist path');
+            process.env.PENNYFARTHING_DIST = actualDistPath;
+            const result = resolvePennyfarthingDist();
+            // When env var is set to valid existing path, should return it
+            assert.strictEqual(result, actualDistPath);
+        });
+        it('should fall through when PENNYFARTHING_DIST is set but path does not exist', () => {
+            // Scenario 1b: Env var set but invalid - should fall through to other checks
+            process.env.PENNYFARTHING_DIST = '/nonexistent/path/pennyfarthing-dist';
+            const result = resolvePennyfarthingDist();
+            // Should fall through and find monorepo path (since we're in monorepo)
+            // The key behavior is it doesn't return the invalid env var path
+            assert.ok(result === null || !result.includes('/nonexistent/'));
+        });
+        it('should find monorepo root pennyfarthing-dist directory', () => {
+            // Scenario 2: Monorepo root detection (dogfooding)
+            // When running from within pennyfarthing repo, find pennyfarthing-dist/ at root
+            delete process.env.PENNYFARTHING_DIST;
+            const result = resolvePennyfarthingDist();
+            // Should find the monorepo root path
+            assert.ok(result !== null, 'Should find monorepo root');
+            assert.ok(result.endsWith('pennyfarthing-dist'), 'Path should end with pennyfarthing-dist');
+        });
+        it('should find sibling pennyfarthing-dist directory', () => {
+            // Scenario 3: Sibling directory for dev scenarios
+            // e.g., project/pennyfarthing-dist when called from project/packages/shared
+            delete process.env.PENNYFARTHING_DIST;
+            const result = resolvePennyfarthingDist();
+            // Implementation should check ../pennyfarthing-dist, ../../pennyfarthing-dist, etc.
+            assert.ok(result === null || result.includes('pennyfarthing-dist'));
+        });
+        it('should find scoped npm package path', () => {
+            // Scenario 4: Scoped npm install
+            // node_modules/@pennyfarthing/core/pennyfarthing-dist/
+            delete process.env.PENNYFARTHING_DIST;
+            const result = resolvePennyfarthingDist();
+            // When installed via @pennyfarthing/core, should find that path
+            assert.ok(result === null || result.includes('pennyfarthing-dist'));
+        });
+        it('should find legacy npm package path', () => {
+            // Scenario 5: Legacy npm install
+            // node_modules/pennyfarthing/pennyfarthing-dist/
+            delete process.env.PENNYFARTHING_DIST;
+            const result = resolvePennyfarthingDist();
+            // When installed via pennyfarthing, should find that path
+            assert.ok(result === null || result.includes('pennyfarthing-dist'));
+        });
+        it('should return a valid path or null', () => {
+            // This tests that the function returns a valid result
+            delete process.env.PENNYFARTHING_DIST;
+            const result = resolvePennyfarthingDist();
+            // Result should be either null or a valid pennyfarthing-dist path
+            if (result !== null) {
+                assert.ok(result.includes('pennyfarthing-dist'));
+            }
+        });
+        it('should check paths in priority order - env var takes precedence', () => {
+            // When multiple paths exist, env var should return first if it exists
+            const actualDistPath = resolvePennyfarthingDist();
+            assert.ok(actualDistPath !== null, 'Should have a valid dist path');
+            // Set env var to actual path
+            process.env.PENNYFARTHING_DIST = actualDistPath;
+            const result = resolvePennyfarthingDist();
+            // Env var should take precedence (returns same path since it exists)
+            assert.strictEqual(result, actualDistPath);
+        });
+    });
+    describe('resolvePortraitPath', () => {
+        it('should resolve portrait by shortName-OCEAN slug from theme YAML', () => {
+            // a-team sm = Faceman, shortName "Faceman", OCEAN scores produce slug
+            const result = resolvePortraitPath('a-team', 'sm');
+            assert.ok(result !== null, 'Should find portrait');
+            assert.ok(result.includes('a-team'), 'Path should include theme');
+            assert.ok(result.endsWith('.png') || result.endsWith('.jpg'), 'Should be image file');
+        });
+        it('should resolve monty-python portraits by shortName-OCEAN slug', () => {
+            const result = resolvePortraitPath('monty-python', 'sm');
+            // monty-python sm = The Announcer, shortName "Announcer", slug "announcer-44441"
+            if (result !== null) {
+                assert.ok(result.includes('monty-python'), 'Path should include theme');
+                assert.ok(result.includes('announcer'), 'Should match by shortName slug');
+            }
+        });
+        it('should return null for invalid theme', () => {
+            const result = resolvePortraitPath('nonexistent-theme', 'sm');
+            assert.strictEqual(result, null);
+        });
+        it('should return null for invalid agent', () => {
+            const result = resolvePortraitPath('a-team', 'nonexistent-agent');
+            assert.strictEqual(result, null);
+        });
+        it('should handle theme with special characters in name', () => {
+            const result = resolvePortraitPath('star-trek-tos', 'sm');
+            assert.ok(result === null || result.includes('star-trek-tos'));
+        });
+        it('should resolve portraits across theme packages', () => {
+            delete process.env.PENNYFARTHING_DIST;
+            const result = resolvePortraitPath('a-team', 'dev');
+            if (result !== null) {
+                assert.ok(result.includes('a-team'));
+                assert.ok(result.endsWith('.png') || result.endsWith('.jpg'));
+            }
+        });
+    });
+    describe('getPortraitPaths', () => {
+        it('should return correct paths structure', () => {
+            const distPath = '/test/pennyfarthing-dist';
+            const result = getPortraitPaths(distPath);
+            assert.ok('portraitsDir' in result, 'Should have portraitsDir');
+            assert.ok('themesDir' in result, 'Should have themesDir');
+            assert.ok('agentsDir' in result, 'Should have agentsDir');
+        });
+        it('should build portraitsDir correctly', () => {
+            const distPath = '/test/pennyfarthing-dist';
+            const result = getPortraitPaths(distPath);
+            // Actual structure: pennyfarthing-dist/personas/portraits/
+            assert.strictEqual(result.portraitsDir, path.join(distPath, 'personas', 'portraits'), 'portraitsDir should be distPath/personas/portraits');
+        });
+        it('should build themesDir correctly', () => {
+            const distPath = '/test/pennyfarthing-dist';
+            const result = getPortraitPaths(distPath);
+            assert.strictEqual(result.themesDir, path.join(distPath, 'personas'), 'themesDir should be distPath/personas');
+        });
+        it('should build agentsDir correctly', () => {
+            const distPath = '/test/pennyfarthing-dist';
+            const result = getPortraitPaths(distPath);
+            assert.strictEqual(result.agentsDir, path.join(distPath, 'agents'), 'agentsDir should be distPath/agents');
+        });
+        it('should handle paths with trailing slashes', () => {
+            const distPath = '/test/pennyfarthing-dist/';
+            const result = getPortraitPaths(distPath);
+            // Should normalize paths correctly
+            assert.ok(!result.portraitsDir.includes('//'), 'Should not have double slashes');
+        });
+    });
+});
+//# sourceMappingURL=portrait-resolver.test.js.map

package/packages/core/dist/shared/portrait-resolver.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portrait-resolver.test.js","sourceRoot":"","sources":["../../src/shared/portrait-resolver.test.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/shared/repos-topology.d.ts

@@ -0,0 +1,49 @@
+/**
+ * repos-topology.ts — Schema validation for repos.yaml topology fields
+ *
+ * Story 87-1: Extend repos.yaml schema with ownership and boundaries.
+ * Validates the spatial awareness fields that agents use to know which
+ * repo owns which paths, what's off-limits, and rendering context.
+ */
+/** Valid values for the ui_layer field */
+export type UiLayer = 'react' | 'cli' | 'none';
+/** Topology-extended repo entry */
+export interface RepoTopology {
+    path: string;
+    type: string;
+    description: string;
+    language?: string;
+    build_command?: string;
+    test_command?: string;
+    lint_command?: string;
+    notes?: string;
+    owns?: string[];
+    never_edit?: string[];
+    symlinks?: Record<string, string>;
+    ui_layer?: UiLayer;
+    components_path?: string;
+}
+/** Top-level repos.yaml structure */
+export interface ReposConfig {
+    repos: Record<string, RepoTopology>;
+}
+/** Validation result */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validate a parsed repos.yaml config for topology schema compliance.
+ * Returns { valid, errors } — never throws.
+ */
+export declare function validateReposTopology(config: unknown): ValidationResult;
+/**
+ * Load and validate repos.yaml from a file path.
+ * Returns the parsed config if valid, or errors if not.
+ */
+export declare function loadReposConfig(filePath: string): Promise<{
+    success: boolean;
+    data?: ReposConfig;
+    errors?: string[];
+}>;
+//# sourceMappingURL=repos-topology.d.ts.map