fraim-hub 2.0.204

package/dist/src/core/utils/git-utils.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isExplicitLocalRepoPath = isExplicitLocalRepoPath;
+exports.getPort = getPort;
+exports.determineDatabaseName = determineDatabaseName;
+exports.getCurrentGitBranch = getCurrentGitBranch;
+exports.determineSchema = determineSchema;
+exports.getDefaultBranch = getDefaultBranch;
+exports.sanitizeRepoIdentifier = sanitizeRepoIdentifier;
+const child_process_1 = require("child_process");
+function extractLocalFolderLabel(rawPath) {
+    const normalized = rawPath
+        .trim()
+        .replace(/^file:\/\//i, '')
+        .replace(/\\/g, '/')
+        .replace(/\/+$/, '');
+    if (!normalized)
+        return undefined;
+    const parts = normalized.split('/').filter(Boolean);
+    const candidate = parts[parts.length - 1];
+    return candidate || undefined;
+}
+function isExplicitLocalRepoPath(repoUrl) {
+    if (!repoUrl || typeof repoUrl !== 'string') {
+        return false;
+    }
+    const trimmed = repoUrl.trim();
+    return (trimmed.startsWith('/') ||
+        trimmed.startsWith('\\') ||
+        /^[a-zA-Z]:[\\/]/.test(trimmed) ||
+        trimmed.startsWith('./') ||
+        trimmed.startsWith('../') ||
+        trimmed.startsWith('file://'));
+}
+function readExplicitPortFromEnv() {
+    for (const value of [
+        process.env.PLAYWRIGHT_FRAIM_MCP_PORT,
+        process.env.PLAYWRIGHT_WEBSITE_PORT,
+        process.env.FRAIM_MCP_PORT,
+        process.env.PORT,
+        process.env.WEBSITES_PORT
+    ]) {
+        const port = Number(value);
+        if (Number.isFinite(port) && port > 0) {
+            return port;
+        }
+    }
+    return null;
+}
+/**
+ * Gets a unique port based on the current git branch name (if it's an issue branch)
+ * Default to 15302 if not on an issue branch
+ */
+function getPort() {
+    // Explicit runtime ports must win so tests and subprocesses all resolve the
+    // same active server instead of drifting back to a branch-derived default.
+    const explicitPort = readExplicitPortFromEnv();
+    if (explicitPort) {
+        return explicitPort;
+    }
+    try {
+        const branchName = process.env.FRAIM_BRANCH || (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD').toString().trim();
+        // Match issue-123 or 123-feature-name or feature/123-name
+        const issueMatch = branchName.match(/issue-(\d+)/i) || branchName.match(/(\d+)-/);
+        if (issueMatch) {
+            const issueNum = parseInt(issueMatch[1], 10);
+            // Ensure port is in a safe range (10000-65535)
+            return 10000 + (issueNum % 55535);
+        }
+    }
+    catch (e) {
+        // Silently fail and use default
+    }
+    return 15302;
+}
+/**
+ * Determines the database name based on the git branch
+ */
+function determineDatabaseName() {
+    try {
+        const branchName = process.env.FRAIM_BRANCH || process.env.FRAIM_BRANCH_NAME || (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD').toString().trim();
+        const issueMatch = branchName.match(/issue-(\d+)/i) || branchName.match(/(\d+)-/);
+        if (issueMatch) {
+            return `fraim_issue_${issueMatch[1]}`;
+        }
+    }
+    catch (e) {
+        // Silently fail
+    }
+    return process.env.MONGODB_DB_NAME || (process.env.NODE_ENV === 'production' ? 'fraim_prod' : 'fraim_dev');
+}
+/**
+ * Gets the current git branch name
+ */
+function getCurrentGitBranch() {
+    try {
+        return (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD', {
+            timeout: 2000, // 2 second timeout
+            stdio: 'pipe'
+        }).toString().trim();
+    }
+    catch (e) {
+        return 'master';
+    }
+}
+/**
+ * Determines the database schema prefix based on the branch
+ */
+function determineSchema(branchName) {
+    const issueMatch = branchName.match(/issue-(\d+)/i) || branchName.match(/(\d+)-/);
+    if (issueMatch) {
+        return `issue_${issueMatch[1]}`;
+    }
+    return 'prod';
+}
+/**
+ * Gets the default branch name from git remote
+ */
+function getDefaultBranch() {
+    try {
+        // Try to get the default branch from remote HEAD
+        const remoteHead = (0, child_process_1.execSync)('git symbolic-ref refs/remotes/origin/HEAD', {
+            timeout: 2000, // 2 second timeout
+            stdio: 'pipe'
+        }).toString().trim();
+        const match = remoteHead.match(/refs\/remotes\/origin\/(.+)$/);
+        if (match) {
+            return match[1];
+        }
+    }
+    catch (e) {
+        // If that fails, try to get it from the current branch
+        try {
+            return getCurrentGitBranch();
+        }
+        catch (e2) {
+            // Fall back to common defaults
+        }
+    }
+    // Default fallback
+    return 'main';
+}
+/**
+ * Sanitizes a repository identifier by stripping local paths and normalizing to standard HTTPS URLs.
+ * Mandatory per Compliance requirement (C1) to ensure data privacy.
+ *
+ * @param repoUrl The raw repository URL or path to sanitize
+ * @returns Normalized HTTPS URL string, or undefined if the input is a local path or invalid
+ */
+function sanitizeRepoIdentifier(repoUrl) {
+    if (!repoUrl || typeof repoUrl !== 'string') {
+        return undefined;
+    }
+    const trimmed = repoUrl.trim();
+    // Convert local paths to just the folder name for privacy-safe workspace labeling.
+    if (isExplicitLocalRepoPath(trimmed)) {
+        return extractLocalFolderLabel(trimmed);
+    }
+    // Normalize GitHub/GitLab SSH and HTTPS URLs
+    // Patterns:
+    // git@github.com:owner/repo.git
+    // https://github.com/owner/repo.git
+    // git@gitlab.com:owner/repo.git
+    // https://gitlab.com/owner/repo.git
+    const gitPattern = /^(?:git@|https:\/\/)(github\.com|gitlab\.com)[:/]([^/]+\/[^/.]+?)(?:\.git)?$/i;
+    const match = trimmed.match(gitPattern);
+    if (match) {
+        const [, domain, path] = match;
+        return `https://${domain.toLowerCase()}/${path}`;
+    }
+    // If it looks like a generic URL but not from approved providers, reject for privacy
+    try {
+        const url = new URL(trimmed);
+        if (url.hostname.includes('github.com') || url.hostname.includes('gitlab.com')) {
+            let path = url.pathname;
+            if (path.startsWith('/'))
+                path = path.substring(1);
+            if (path.endsWith('.git'))
+                path = path.substring(0, path.length - 4);
+            // Only return if it matches owner/repo structure
+            if (path.split('/').length >= 2) {
+                return `https://${url.hostname.toLowerCase()}/${path}`;
+            }
+        }
+    }
+    catch (e) {
+        // Not a valid URL
+    }
+    // Preserve plain folder labels that are already privacy-safe and not path-like.
+    if (!trimmed.includes('/') && !trimmed.includes('\\') && !trimmed.includes('://')) {
+        return trimmed;
+    }
+    return undefined;
+}

package/dist/src/core/utils/ports.js

@@ -0,0 +1,32 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findAvailablePort = findAvailablePort;
+exports.findAvailablePortExcluding = findAvailablePortExcluding;
+const net_1 = __importDefault(require("net"));
+async function findAvailablePort(preferredPort) {
+    return findAvailablePortExcluding(preferredPort, new Set());
+}
+async function findAvailablePortExcluding(preferredPort, excludedPorts) {
+    let port = preferredPort;
+    while (port < preferredPort + 20) {
+        if (excludedPorts.has(port)) {
+            port += 1;
+            continue;
+        }
+        const available = await new Promise((resolve) => {
+            const server = net_1.default.createServer();
+            server.once('error', () => resolve(false));
+            server.once('listening', () => {
+                server.close(() => resolve(true));
+            });
+            server.listen(port, '127.0.0.1');
+        });
+        if (available)
+            return port;
+        port += 1;
+    }
+    throw new Error(`No free loopback port found near ${preferredPort}.`);
+}

package/dist/src/core/utils/project-fraim-paths.js

@@ -0,0 +1,220 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKSPACE_SYNCED_CONTENT_DIRS = exports.WORKSPACE_FRAIM_DIRNAME = void 0;
+exports.getWorkspaceFraimDir = getWorkspaceFraimDir;
+exports.workspaceFraimExists = workspaceFraimExists;
+exports.getWorkspaceConfigPath = getWorkspaceConfigPath;
+exports.getWorkspaceFraimPath = getWorkspaceFraimPath;
+exports.assertWorkspaceFraimRoot = assertWorkspaceFraimRoot;
+exports.assertWorkspaceFraimPath = assertWorkspaceFraimPath;
+exports.createWorkspaceFraimPathAsserter = createWorkspaceFraimPathAsserter;
+exports.assertExactWorkspaceFraimPath = assertExactWorkspaceFraimPath;
+exports.getWorkspaceFraimDisplayPath = getWorkspaceFraimDisplayPath;
+exports.getUserFraimDisplayPath = getUserFraimDisplayPath;
+exports.getUserFraimDirPath = getUserFraimDirPath;
+exports.getUserFraimLearningsDir = getUserFraimLearningsDir;
+exports.getWorkspaceLearningsDir = getWorkspaceLearningsDir;
+exports.getConfiguredPortableLearningsDir = getConfiguredPortableLearningsDir;
+exports.getConfiguredPortableLearningsDisplayPath = getConfiguredPortableLearningsDisplayPath;
+exports.getEffectiveFraimDir = getEffectiveFraimDir;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = __importDefault(require("os"));
+exports.WORKSPACE_FRAIM_DIRNAME = 'fraim';
+exports.WORKSPACE_SYNCED_CONTENT_DIRS = [
+    'workflows',
+    'ai-employee',
+    'ai-manager',
+    'docs'
+];
+function normalizeRelativePath(relativePath) {
+    return relativePath.replace(/^[\\/]+/, '').replace(/[\\/]+/g, '/');
+}
+function normalizeDisplayPath(fullPath) {
+    return fullPath.replace(/\\/g, '/');
+}
+function getWorkspaceFraimDir(projectRoot = process.cwd()) {
+    return (0, path_1.join)(projectRoot, exports.WORKSPACE_FRAIM_DIRNAME);
+}
+function isPathInsideOrEqual(parentPath, childPath) {
+    const relativePath = (0, path_1.relative)(parentPath, childPath);
+    return relativePath === '' || (relativePath.length > 0 &&
+        !relativePath.startsWith('..') &&
+        !(0, path_1.isAbsolute)(relativePath));
+}
+function realpathIfExists(fullPath) {
+    try {
+        return fs_1.realpathSync.native(fullPath);
+    }
+    catch {
+        return null;
+    }
+}
+function deepestExistingAncestor(fullPath) {
+    let current = (0, path_1.resolve)(fullPath);
+    while (!(0, fs_1.existsSync)(current)) {
+        const parent = (0, path_1.dirname)(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+    return current;
+}
+function workspaceFraimExists(projectRoot = process.cwd()) {
+    try {
+        return (0, fs_1.readdirSync)(projectRoot, { withFileTypes: true }).some((entry) => entry.isDirectory() && entry.name === exports.WORKSPACE_FRAIM_DIRNAME);
+    }
+    catch {
+        return false;
+    }
+}
+function getWorkspaceConfigPath(projectRoot = process.cwd()) {
+    return (0, path_1.join)(getWorkspaceFraimDir(projectRoot), 'config.json');
+}
+function getWorkspaceFraimPath(projectRoot = process.cwd(), ...parts) {
+    return (0, path_1.join)(getWorkspaceFraimDir(projectRoot), ...parts);
+}
+function assertWorkspaceFraimRoot(projectRoot = process.cwd()) {
+    const resolvedProjectRoot = (0, path_1.resolve)(projectRoot);
+    const fraimDir = getWorkspaceFraimDir(resolvedProjectRoot);
+    if (!workspaceFraimExists(resolvedProjectRoot)) {
+        throw new Error(`Refusing to use FRAIM workspace root "${resolvedProjectRoot}": expected exact lowercase fraim directory at "${fraimDir}".`);
+    }
+    const projectRootRealPath = realpathIfExists(resolvedProjectRoot);
+    const fraimRealPath = realpathIfExists(fraimDir);
+    if (projectRootRealPath &&
+        fraimRealPath &&
+        !isPathInsideOrEqual(projectRootRealPath, fraimRealPath)) {
+        throw new Error(`Refusing to use FRAIM workspace root "${resolvedProjectRoot}": "${fraimDir}" resolves outside the project root.`);
+    }
+    return fraimDir;
+}
+function assertWorkspaceFraimPath(projectRoot = process.cwd(), targetPath) {
+    createWorkspaceFraimPathAsserter(projectRoot)(targetPath);
+}
+function createWorkspaceFraimPathAsserter(projectRoot = process.cwd()) {
+    const fraimDir = assertWorkspaceFraimRoot(projectRoot);
+    const resolvedFraimDir = (0, path_1.resolve)(fraimDir);
+    const fraimRealPath = realpathIfExists(fraimDir);
+    const realpathCache = new Map();
+    const cachedRealpath = (fullPath) => {
+        const resolvedPath = (0, path_1.resolve)(fullPath);
+        if (!realpathCache.has(resolvedPath)) {
+            realpathCache.set(resolvedPath, realpathIfExists(resolvedPath));
+        }
+        return realpathCache.get(resolvedPath) ?? null;
+    };
+    return (targetPath) => {
+        const resolvedTargetPath = (0, path_1.resolve)(targetPath);
+        if (resolvedTargetPath === resolvedFraimDir ||
+            !isPathInsideOrEqual(resolvedFraimDir, resolvedTargetPath)) {
+            throw new Error(`Refusing to use FRAIM workspace path "${resolvedTargetPath}": expected a path under "${resolvedFraimDir}".`);
+        }
+        const existingAncestor = deepestExistingAncestor(resolvedTargetPath);
+        const ancestorRealPath = existingAncestor ? cachedRealpath(existingAncestor) : null;
+        if (fraimRealPath &&
+            ancestorRealPath &&
+            !isPathInsideOrEqual(fraimRealPath, ancestorRealPath)) {
+            throw new Error(`Refusing to use FRAIM workspace path "${resolvedTargetPath}": existing path "${existingAncestor}" resolves outside "${fraimDir}".`);
+        }
+    };
+}
+function assertExactWorkspaceFraimPath(projectRoot = process.cwd(), targetPath, ...parts) {
+    const expectedPath = (0, path_1.resolve)(getWorkspaceFraimDir((0, path_1.resolve)(projectRoot)), ...parts);
+    const resolvedTargetPath = (0, path_1.resolve)(targetPath);
+    if (resolvedTargetPath !== expectedPath) {
+        throw new Error(`Refusing to use FRAIM workspace path "${resolvedTargetPath}": expected exact managed path "${expectedPath}".`);
+    }
+    assertWorkspaceFraimPath(projectRoot, targetPath);
+}
+function getWorkspaceFraimDisplayPath(relativePath = '') {
+    const normalized = normalizeRelativePath(relativePath);
+    return normalized.length > 0
+        ? `${exports.WORKSPACE_FRAIM_DIRNAME}/${normalized}`
+        : `${exports.WORKSPACE_FRAIM_DIRNAME}/`;
+}
+function getUserFraimDisplayPath(relativePath = '') {
+    const normalized = normalizeRelativePath(relativePath);
+    return normalized.length > 0 ? `~/.fraim/${normalized}` : '~/.fraim/';
+}
+/**
+ * Get the user-level FRAIM directory (~/.fraim/).
+ * Can be overridden with FRAIM_USER_DIR env var for testing.
+ */
+function getUserFraimDirPath() {
+    return process.env.FRAIM_USER_DIR || (0, path_1.join)(os_1.default.homedir(), '.fraim');
+}
+function getUserFraimLearningsDir() {
+    return (0, path_1.join)(getUserFraimDirPath(), 'personalized-employee', 'learnings');
+}
+function getWorkspaceLearningsDir(projectRoot = process.cwd()) {
+    return getWorkspaceFraimPath(projectRoot, 'personalized-employee', 'learnings');
+}
+function resolveConfiguredLearningGlobalPath(rawPath) {
+    if (typeof rawPath !== 'string')
+        return null;
+    const trimmed = rawPath.trim();
+    if (!trimmed)
+        return null;
+    if (/^[a-z]+:\/\//i.test(trimmed))
+        return null;
+    if (trimmed.startsWith('~')) {
+        const homeRelative = trimmed.slice(1).replace(/^[\\/]+/, '');
+        return (0, path_1.normalize)((0, path_1.join)(os_1.default.homedir(), homeRelative));
+    }
+    if (!(0, path_1.isAbsolute)(trimmed))
+        return null;
+    return (0, path_1.normalize)(trimmed);
+}
+function readWorkspaceConfig(projectRoot) {
+    try {
+        const configPath = getWorkspaceConfigPath(projectRoot);
+        if (!(0, fs_1.existsSync)(configPath))
+            return null;
+        return JSON.parse((0, fs_1.readFileSync)(configPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function getConfiguredPortableLearningsDir(projectRoot = process.cwd()) {
+    const config = readWorkspaceConfig(projectRoot);
+    const configured = resolveConfiguredLearningGlobalPath(config?.learning?.globalPath);
+    return configured || getUserFraimLearningsDir();
+}
+function getConfiguredPortableLearningsDisplayPath(projectRoot = process.cwd()) {
+    const config = readWorkspaceConfig(projectRoot);
+    const configured = resolveConfiguredLearningGlobalPath(config?.learning?.globalPath);
+    if (configured) {
+        return normalizeDisplayPath(configured);
+    }
+    return getUserFraimDisplayPath('personalized-employee/learnings').replace(/\/$/, '');
+}
+/**
+ * Determine the effective FRAIM content root directory.
+ *
+ * Shadow semantics: if the project has a local fraim/ directory, it completely
+ * shadows the user-level ~/.fraim/ — no mixing, no layering.
+ *
+ * @param projectRoot - The project/workspace root directory
+ * @param userFraimDir - Optional override for the user-level dir (for testing)
+ * @returns The effective fraim content root directory path, or '' if neither exists
+ */
+function getEffectiveFraimDir(projectRoot = process.cwd(), userFraimDir) {
+    // 1. Check for project-level fraim/ directory
+    const projectFraimDir = getWorkspaceFraimDir(projectRoot);
+    if (workspaceFraimExists(projectRoot)) {
+        return projectFraimDir;
+    }
+    // 2. Fall back to user-level ~/.fraim/
+    const userDir = userFraimDir || getUserFraimDirPath();
+    if ((0, fs_1.existsSync)(userDir)) {
+        return userDir;
+    }
+    // 3. Neither exists
+    return '';
+}

package/dist/src/db/payment-repository.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentRepository = void 0;
+const COLLECTION_NAME = 'fraim_payments';
+class PaymentRepository {
+    constructor(client, dbName = 'fraim') {
+        this.db = client.db(dbName);
+        this.collection = this.db.collection(COLLECTION_NAME);
+    }
+    async ensureIndexes() {
+        await this.collection.createIndex({ email: 1 });
+        await this.collection.createIndex({ timestamp: -1 });
+        await this.collection.createIndex({ status: 1 });
+        await this.collection.createIndex({ stripeCustomerId: 1 });
+    }
+    async createPayment(payment) {
+        const result = await this.collection.insertOne(payment);
+        return { ...payment, _id: result.insertedId.toString() };
+    }
+    async updatePaymentStatus(stripePaymentIntentId, status, metadata) {
+        const result = await this.collection.updateOne({ stripePaymentIntentId }, {
+            $set: {
+                status,
+                ...(metadata && { metadata })
+            }
+        });
+        return result.modifiedCount > 0;
+    }
+    async getPaymentById(id) {
+        return await this.collection.findOne({ _id: id });
+    }
+    async getPaymentByStripePaymentIntent(stripePaymentIntentId) {
+        return await this.collection.findOne({ stripePaymentIntentId });
+    }
+    async getPaymentsByEmail(email) {
+        return await this.collection.find({ email }).sort({ timestamp: -1 }).toArray();
+    }
+    async listPayments(filters) {
+        const query = {};
+        if (filters.plan)
+            query.plan = filters.plan;
+        if (filters.status)
+            query.status = filters.status;
+        if (filters.startDate || filters.endDate) {
+            query.timestamp = {};
+            if (filters.startDate)
+                query.timestamp.$gte = filters.startDate;
+            if (filters.endDate)
+                query.timestamp.$lte = filters.endDate;
+        }
+        const total = await this.collection.countDocuments(query);
+        const payments = await this.collection
+            .find(query)
+            .sort({ timestamp: -1 })
+            .skip(filters.offset || 0)
+            .limit(filters.limit || 50)
+            .toArray();
+        return { payments, total };
+    }
+}
+exports.PaymentRepository = PaymentRepository;

package/dist/src/first-run/types.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Setup checklist surface — the row-keyed model that replaces the prior
+ * linear step machine for issue #352 v1.
+ *
+ * The same surface serves every user. What changes between a fresh-machine
+ * run and an experienced-engineer run is the distribution of row statuses,
+ * not the surface itself. Per R2.0 acceptance, the DOM and CSS chrome are
+ * byte-identical between cases — only `data-row-status`, the verb-text
+ * node, and the primary-button label differ.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIRST_RUN_AGENT_OPTIONS = exports.FIRST_RUN_RESOURCES_URL = exports.FIRST_RUN_PROMPT = exports.FIRST_RUN_ROW_IDS = void 0;
+exports.createInitialRows = createInitialRows;
+exports.derivePrimaryButtonLabel = derivePrimaryButtonLabel;
+exports.FIRST_RUN_ROW_IDS = [
+    'node',
+    'git',
+    'agent',
+    'fraim',
+];
+exports.FIRST_RUN_PROMPT = 'Onboard this project';
+exports.FIRST_RUN_RESOURCES_URL = 'https://fraimworks.ai/resources.html';
+/**
+ * Recommended-agent priority order (R2.2).
+ * Tie-break: Claude Code first, then Codex, then Gemini.
+ */
+exports.FIRST_RUN_AGENT_OPTIONS = [
+    {
+        id: 'claude-code',
+        label: 'Claude Code',
+        detectAliases: ['claude-code', 'claude code', 'claude'],
+        loginCommand: 'claude',
+        launchCommand: 'claude',
+        installPackage: '@anthropic-ai/claude-code',
+    },
+    {
+        id: 'codex',
+        label: 'Codex',
+        detectAliases: ['codex'],
+        loginCommand: 'codex login',
+        launchCommand: 'codex',
+        installPackage: '@openai/codex',
+    },
+    {
+        id: 'gemini-cli',
+        label: 'Gemini CLI',
+        detectAliases: ['gemini-cli', 'gemini cli', 'gemini'],
+        loginCommand: 'gemini',
+        launchCommand: 'gemini',
+        installPackage: '@google/gemini-cli',
+    },
+    {
+        id: 'copilot-cli',
+        label: 'GitHub Copilot CLI',
+        detectAliases: ['copilot', 'copilot-cli', 'github copilot cli'],
+        loginCommand: 'copilot login',
+        launchCommand: 'copilot',
+        installPackage: '@github/copilot',
+    },
+];
+/**
+ * The canonical row set, in display order. Each row starts in `pending`;
+ * detection updates statuses on session load.
+ */
+function createInitialRows() {
+    return [
+        { id: 'node', label: 'Node.js', status: 'pending', verb: "we'll install" },
+        { id: 'git', label: 'git', status: 'pending', verb: "we'll install", optional: true },
+        { id: 'agent', label: 'Locally installed AI agents', status: 'pending', verb: "we'll detect local AI agents" },
+        { id: 'fraim', label: 'FRAIM', status: 'pending', verb: "we'll set up FRAIM" },
+    ];
+}
+/**
+ * State-derived primary-button label per R2.0. NEVER audience-derived.
+ *
+ * - "Get Started": every row is ok, OR every row is ok-or-manual-required
+ *   (skip-path: user explicitly handled remaining steps via Skip-and-continue).
+ *   Clicking "Get Started" shows the user-type selection screen (#367).
+ * - "Continue": at least one row is ok and there is still wizard work to do.
+ * - "Set up FRAIM": no rows ok yet.
+ */
+function derivePrimaryButtonLabel(rows) {
+    // Optional rows (e.g. git) never block wizard progression.
+    const required = rows.filter((row) => !row.optional);
+    const allOk = required.every((row) => row.status === 'ok');
+    if (allOk)
+        return 'Get Started';
+    // Skip-path: every required row is ok-or-manual-required — nothing left for the wizard.
+    if (required.some((row) => row.status === 'ok'))
+        return 'Continue';
+    return 'Set up FRAIM';
+}