Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Read-only, bounded workspace readiness probes for the persistent mind.
*
* This module deliberately returns semantic facts only. Probe output, paths,
* branch names, remotes, and arbitrary configuration values never cross the
* service boundary. The in-memory cache is per PortOS process and is a
* diagnostic freshness aid, not a persisted source of truth.
*/
import { opendir, readFile, readdir, stat } from 'fs/promises';
import { isAbsolute, join, relative, resolve } from 'path';
import { promisify } from 'util';
import { execFile } from '../lib/childProcess.js';
import { commandExists } from '../lib/commandExists.js';
import { execGit } from '../lib/execGit.js';
import { withSpawnCwdEnv } from '../lib/spawnCwd.js';
import { resolveAppForgeTarget } from '../lib/workTracker.js';
import {
PERSISTENT_MIND_VALIDATION_CHECKS,
} from '../lib/persistentMindCapabilities.js';
import {
isCliReviewer,
isReviewer,
} from '../lib/validation.js';
import { compareVersions, satisfiesVersionRequirement } from '../../scripts/checkNodeVersion.js';
export { satisfiesVersionRequirement } from '../../scripts/checkNodeVersion.js';
import * as codeReview from './codeReview.js';
const execFileAsync = promisify(execFile);
export const PERSISTENT_MIND_WORKSPACE_PREFLIGHT_SCHEMA_VERSION = 1;
export const PERSISTENT_MIND_WORKSPACE_PREFLIGHT_TTL_MS = 30_000;
export const PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS = Object.freeze({
maxApps: 25,
maxAppIdChars: 128,
maxAppNameChars: 100,
maxWorkspaces: 20,
maxDirectoryEntries: 100,
maxPackageManifestBytes: 256 * 1024,
maxScriptNames: 20,
maxScriptNameChars: 100,
maxWorkspaceIdChars: 200,
maxEngineRequirementChars: 200,
maxGitOutputBytes: 64 * 1024,
probeTimeoutMs: 5_000,
});
const LOCKFILES = Object.freeze([
{ filename: 'package-lock.json', type: 'npm' },
{ filename: 'npm-shrinkwrap.json', type: 'npm-shrinkwrap' },
{ filename: 'pnpm-lock.yaml', type: 'pnpm' },
{ filename: 'yarn.lock', type: 'yarn' },
{ filename: 'bun.lockb', type: 'bun' },
{ filename: 'bun.lock', type: 'bun' },
]);
const PACKAGE_MANAGER_COMMANDS = Object.freeze({ npm: 'npm', pnpm: 'pnpm', yarn: 'yarn', bun: 'bun' });
const FORGE_COMMANDS = Object.freeze({ github: 'gh', gitlab: 'glab' });
const FORGE_AUTH_ARGS = Object.freeze({
github: ['auth', 'status'],
gitlab: ['auth', 'status'],
});
const FORGE_TRACKERS = new Set(['github', 'gitlab']);
const defaultDependencies = {
readFile,
readdir,
opendir,
stat,
execGit,
commandExists,
execFile: execFileAsync,
resolveAppForgeTarget,
getCodeReviewDefaults: (...args) => typeof codeReview.getCodeReviewDefaults === 'function'
? codeReview.getCodeReviewDefaults(...args)
: Promise.resolve(null),
getReviewerCliInstalled: (...args) => typeof codeReview.getReviewerCliInstalled === 'function'
? codeReview.getReviewerCliInstalled(...args)
: Promise.resolve(null),
};
const cache = new Map();
const isRecord = (value) => value && typeof value === 'object' && !Array.isArray(value);
const nowValue = (clock) => {
const value = typeof clock === 'function' ? clock() : clock;
return Number.isFinite(value) ? value : Date.now();
};
const isMissing = (error) => error?.code === 'ENOENT';
const isPathLike = (value) => typeof value === 'string' && (
isAbsolute(value)
|| /^[A-Za-z]:[\\/]/.test(value)
|| /^~[\\/]/.test(value)
);
const isTimeout = (error) => Boolean(
error?.code === 'ETIMEDOUT'
|| error?.killed === true
|| error?.signal === 'SIGTERM'
);
const normalizeRelativePath = (value) => {
if (typeof value !== 'string') return null;
const normalized = value.trim().replaceAll('\\', '/');
if (!normalized || normalized === '.') return '.';
if (normalized.length > PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxWorkspaceIdChars) return null;
if (normalized.startsWith('/') || /^[A-Za-z]:\//.test(normalized) || isAbsolute(normalized)) return null;
const parts = normalized.split('/').filter(Boolean);
if (parts.some((part) => part === '..' || part === '.')) return null;
return parts.join('/');
};
const relativeWorkspaceId = (repoPath, workspacePath) => {
const value = relative(repoPath, workspacePath).replaceAll('\\', '/');
return (value || 'root').slice(0, PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxWorkspaceIdChars);
};
const pathForWorkspace = (repoPath, workspaceId) => resolve(repoPath, workspaceId === 'root' ? '.' : workspaceId);
const readPathState = (filePath, dependencies) => dependencies.stat(filePath)
.then((info) => ({
state: 'present',
isDirectory: typeof info?.isDirectory === 'function' ? info.isDirectory() : null,
size: Number.isFinite(info?.size) ? Number(info.size) : null,
}))
.catch((error) => ({ state: isMissing(error) ? 'missing' : 'unknown' }));
const readPackageManifest = (filePath, dependencies) => dependencies.stat(filePath)
.then((info) => {
if (Number.isFinite(info?.size) && info.size > PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxPackageManifestBytes) {
return { state: 'truncated', value: null };
}
return dependencies.readFile(filePath, 'utf8')
.then((content) => Promise.resolve().then(() => JSON.parse(String(content))))
.then((value) => ({ state: isRecord(value) ? 'ready' : 'unknown', value: isRecord(value) ? value : null }))
.catch((error) => ({
state: isMissing(error) ? 'missing' : 'unknown',
value: null,
}));
})
.catch((error) => ({ state: isMissing(error) ? 'missing' : 'unknown', value: null }));
const readDirectoryEntries = async (directoryPath, dependencies) => {
// Keep an injected array reader useful for fixture tests, while the real
// probe streams directory entries and stops after the safety bound plus one
// sentinel. `readdir()` materializes an arbitrarily large directory before
// the slice can be applied.
if (dependencies.readdir !== readdir) return dependencies.readdir(directoryPath, { withFileTypes: true });
const directory = await dependencies.opendir(directoryPath);
const entries = [];
for await (const entry of directory) {
entries.push(entry);
if (entries.length > PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxDirectoryEntries) break;
}
return entries;
};
const readDirectoryNames = (directoryPath, dependencies) => Promise.resolve()
.then(() => readDirectoryEntries(directoryPath, dependencies))
.then((entries) => {
const bounded = Array.isArray(entries) ? entries.slice(0, PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxDirectoryEntries) : [];
return {
names: bounded
.filter((entry) => typeof entry?.name === 'string' && (typeof entry.isDirectory !== 'function' || entry.isDirectory()))
.map((entry) => entry.name)
.sort(),
truncated: Array.isArray(entries) && entries.length > bounded.length,
unknown: false,
};
})
.catch(() => ({ names: [], truncated: false, unknown: true }));
const workspacePatterns = (manifest) => {
const raw = manifest?.workspaces;
if (Array.isArray(raw)) return raw;
if (isRecord(raw) && Array.isArray(raw.packages)) return raw.packages;
return [];
};
const safeEngineRequirement = (value) => {
if (typeof value !== 'string' || !value.trim()) return null;
const normalized = value.trim();
return /^[vV0-9xX*<>=~^|.,\s-]+$/.test(normalized)
? normalized.slice(0, PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxEngineRequirementChars)
: 'unknown';
};
const expandWorkspacePattern = (repoPath, pattern, dependencies) => {
const normalized = normalizeRelativePath(pattern);
if (!normalized) return Promise.resolve({ paths: [], truncated: true });
const segments = normalized.split('/');
const hasGlob = segments.some((segment) => segment === '*');
if (!hasGlob) return Promise.resolve({ paths: [pathForWorkspace(repoPath, normalized)], truncated: false });
if (segments.some((segment) => segment !== '*' && /[*?\[\]]/.test(segment))) {
return Promise.resolve({ paths: [], truncated: true });
}
const walk = async (basePath, index) => {
if (index >= segments.length) return { paths: [basePath], truncated: false, unknown: false };
const segment = segments[index];
if (segment !== '*') return walk(join(basePath, segment), index + 1);
const { names, truncated: listingTruncated, unknown: listingUnknown } = await readDirectoryNames(basePath, dependencies);
const paths = [];
let truncated = listingTruncated;
let unknown = listingUnknown;
for (const name of names) {
if (paths.length >= PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxWorkspaces) {
truncated = true;
break;
}
const result = await walk(join(basePath, name), index + 1);
paths.push(...result.paths.slice(0, PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxWorkspaces - paths.length));
truncated ||= result.truncated;
unknown ||= result.unknown;
if (paths.length >= PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxWorkspaces) truncated = true;
}
return { paths, truncated, unknown };
};
return walk(repoPath, 0);
};
const discoverWorkspacePaths = async (repoPath, manifest, dependencies) => {
const patterns = workspacePatterns(manifest);
if (!patterns.length) return { paths: [repoPath], truncated: false };
const expanded = await Promise.all(patterns.slice(0, PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxWorkspaces).map(
(pattern) => expandWorkspacePattern(repoPath, pattern, dependencies)
));
const paths = [repoPath, ...expanded.flatMap((item) => item.paths || [])];
const unique = [...new Set(paths)].slice(0, PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxWorkspaces);
return {
paths: unique,
truncated: patterns.length > PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxWorkspaces
|| expanded.some((item) => item.truncated)
|| paths.length > unique.length,
unknown: expanded.some((item) => item.unknown),
};
};
const scriptNames = (manifest) => {
const scripts = isRecord(manifest?.scripts) ? Object.keys(manifest.scripts) : [];
const pick = (prefix) => scripts
.filter((name) => name === prefix || name.startsWith(`${prefix}:`) || name.startsWith(`${prefix}-`))
.sort()
.slice(0, PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxScriptNames);
const bound = (names) => names.map((name) => name.slice(0, PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxScriptNameChars));
return { test: bound(pick('test')), build: bound(pick('build')) };
};
const engineRequirements = (manifest) => {
const engines = isRecord(manifest?.engines) ? manifest.engines : {};
const manager = Object.keys(PACKAGE_MANAGER_COMMANDS).find((name) => typeof engines[name] === 'string' && engines[name].trim());
const packageManager = typeof manifest?.packageManager === 'string'
? manifest.packageManager.trim().match(/^([a-z]+)@(.+)$/i)
: null;
const packageManagerName = packageManager && PACKAGE_MANAGER_COMMANDS[packageManager[1].toLowerCase()]
? packageManager[1].toLowerCase()
: manager || null;
const packageManagerRequirement = packageManagerName
? (safeEngineRequirement(engines[packageManagerName])
|| (packageManager?.[2] ? /^v?\d+(?:\.\d+){0,2}(?:-[0-9A-Za-z.-]+)?$/.test(packageManager[2].trim())
? `=${packageManager[2].trim().slice(0, PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxEngineRequirementChars - 1)}`
: 'unknown' : null))
: null;
return {
node: safeEngineRequirement(engines.node),
packageManager: packageManagerName ? {
name: packageManagerName,
required: packageManagerRequirement,
} : null,
};
};
const normalizeVersion = (value) => {
const match = String(value || '').trim().match(/^v?\d+(?:\.\d+){0,2}(?:-[0-9A-Za-z.-]+)?$/);
return match ? match[0].replace(/^v/, '') : null;
};
const actualVersion = (output) => {
const match = String(output || '').match(/\bv?\d+(?:\.\d+){1,2}(?:-[0-9A-Za-z.-]+)?\b/);
return normalizeVersion(match?.[0]);
};
const compatibility = (actual, required) => {
const normalizedActual = normalizeVersion(actual);
if (!required) return { required: null, actual: normalizedActual, status: 'not-declared' };
const result = satisfiesVersionRequirement(normalizedActual, required);
return {
required,
actual: normalizedActual,
status: result === true ? 'compatible' : result === false ? 'incompatible' : 'unknown',
};
};
const safeGit = (args, cwd, dependencies) => dependencies.execGit(args, cwd, {
ignoreExitCode: true,
maxBuffer: PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxGitOutputBytes,
timeout: PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.probeTimeoutMs,
}).then((result) => result).catch(() => null);
const inspectRepository = async (app, dependencies) => {
const repoPath = typeof app?.repoPath === 'string' ? app.repoPath.trim() : '';
if (!repoPath) {
return {
repository: { configured: false, reachable: false },
checkout: { state: 'unknown' },
};
}
const pathState = await readPathState(repoPath, dependencies);
if (pathState.state === 'missing' || pathState.isDirectory === false) {
return {
repository: { configured: true, reachable: false },
checkout: { state: 'unknown' },
};
}
if (pathState.state !== 'present') {
return {
repository: { configured: true, reachable: null },
checkout: { state: 'unknown' },
};
}
const reachableProbe = await safeGit(['rev-parse', '--is-inside-work-tree'], repoPath, dependencies);
if (!reachableProbe) {
return {
repository: { configured: true, reachable: null },
checkout: { state: 'unknown' },
};
}
if (reachableProbe.exitCode !== 0 || String(reachableProbe.stdout || '').trim() !== 'true') {
return {
repository: { configured: true, reachable: false },
checkout: { state: 'unknown' },
};
}
const statusProbe = await safeGit(['status', '--porcelain', '--untracked-files=all'], repoPath, dependencies);
return {
repository: { configured: true, reachable: true },
checkout: {
state: statusProbe && statusProbe.exitCode === 0
? String(statusProbe.stdout || '').trim() ? 'dirty' : 'clean'
: 'unknown',
},
};
};
const inspectLockfile = async (workspacePath, repoPath, dependencies) => {
const localChecks = await Promise.all(LOCKFILES.map(async (candidate) => ({
...candidate,
result: await readPathState(join(workspacePath, candidate.filename), dependencies),
})));
const localPresent = localChecks.find((candidate) => candidate.result.state === 'present');
if (localPresent) return { status: 'present', type: localPresent.type, scope: 'workspace' };
if (localChecks.some((candidate) => candidate.result.state === 'unknown')) {
return { status: 'unknown', type: null, scope: null };
}
if (workspacePath === repoPath) return { status: 'absent', type: null, scope: null };
const rootChecks = await Promise.all(LOCKFILES.map(async (candidate) => ({
...candidate,
result: await readPathState(join(repoPath, candidate.filename), dependencies),
})));
const rootPresent = rootChecks.find((candidate) => candidate.result.state === 'present');
if (rootPresent) return { status: 'present', type: rootPresent.type, scope: 'root' };
if (rootChecks.some((candidate) => candidate.result.state === 'unknown')) {
return { status: 'unknown', type: null, scope: null };
}
return { status: 'absent', type: null, scope: null };
};
const inspectDependencies = async (workspacePath, repoPath, dependencies) => {
const local = await readPathState(join(workspacePath, 'node_modules'), dependencies);
if (local.state === 'present' && local.isDirectory !== false) return { status: 'installed', source: 'workspace' };
if (local.state === 'unknown') return { status: 'unknown', source: null };
if (workspacePath === repoPath) return { status: 'absent', source: null };
const root = await readPathState(join(repoPath, 'node_modules'), dependencies);
if (root.state === 'present' && root.isDirectory !== false) return { status: 'installed', source: 'root' };
if (root.state === 'unknown') return { status: 'unknown', source: null };
return { status: 'absent', source: null };
};
const readManagerVersions = async (names, repoPath, dependencies, runtime) => {
const configured = isRecord(runtime?.packageManagerVersions) ? runtime.packageManagerVersions : {};
const entries = await Promise.all([...names].map(async (name) => {
if (typeof configured[name] === 'string' && configured[name].trim()) return [name, actualVersion(configured[name])];
const command = PACKAGE_MANAGER_COMMANDS[name];
if (!command) return [name, null];
const result = await dependencies.execFile(command, ['--version'], {
cwd: repoPath,
env: withSpawnCwdEnv(process.env, repoPath),
timeout: PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.probeTimeoutMs,
maxBuffer: 4 * 1024,
}).catch(() => null);
return [name, result ? actualVersion(result.stdout ?? result) : null];
}));
return Object.fromEntries(entries);
};
const inspectSubmodules = async (repoPath, dependencies) => {
const gitmodules = await readPathState(join(repoPath, '.gitmodules'), dependencies);
if (gitmodules.state === 'missing') return { configured: false, status: 'not-configured', initialized: null };
if (gitmodules.state !== 'present') return { configured: null, status: 'unknown', initialized: null };
const result = await safeGit(['submodule', 'status', '--recursive'], repoPath, dependencies);
if (!result || result.exitCode !== 0) return { configured: true, status: 'unknown', initialized: null };
const lines = String(result.stdout || '').split(/\r?\n/).filter(Boolean);
const uninitialized = lines.some((line) => line.startsWith('-'));
return {
configured: true,
status: uninitialized ? 'uninitialized' : 'initialized',
initialized: !uninitialized,
};
};
const inspectForge = async (app, repository, dependencies) => {
const resolution = await dependencies.resolveAppForgeTarget(app).catch(() => null);
const target = resolution?.target;
const tracker = resolution?.tracker;
const forge = target?.forge || (FORGE_TRACKERS.has(tracker) ? tracker : null);
if (!forge) {
return { provider: 'none', cli: null, installed: null, authenticated: null, status: 'not-configured' };
}
if (!FORGE_COMMANDS[forge]) {
return { provider: 'unknown', cli: null, installed: null, authenticated: null, status: 'unknown' };
}
if (repository.reachable !== true) {
return { provider: forge, cli: FORGE_COMMANDS[forge], installed: null, authenticated: null, status: 'unknown' };
}
const cli = FORGE_COMMANDS[forge];
const installed = await dependencies.commandExists(cli, ['--version'], {
cwd: typeof app.repoPath === 'string' ? app.repoPath : undefined,
timeoutMs: PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.probeTimeoutMs,
}).catch(() => false);
if (!installed) return { provider: forge, cli, installed: false, authenticated: false, status: 'unavailable' };
const authArgs = target?.apiHost
? [...FORGE_AUTH_ARGS[forge], '--hostname', target.apiHost]
: FORGE_AUTH_ARGS[forge];
const authResult = await dependencies.execFile(cli, authArgs, {
cwd: app.repoPath,
env: withSpawnCwdEnv(process.env, app.repoPath),
timeout: PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.probeTimeoutMs,
maxBuffer: 8 * 1024,
}).then(() => true).catch((error) => isTimeout(error) ? null : false);
return {
provider: forge,
cli,
installed: true,
authenticated: authResult,
status: authResult === true ? 'ready' : authResult === false ? 'unavailable' : 'unknown',
};
};
const reviewerAvailability = (reviewer, forge, installed) => {
if (isCliReviewer(reviewer)) return installed && Object.hasOwn(installed, reviewer) ? installed[reviewer] : null;
if (reviewer === 'copilot') {
if (forge?.provider !== 'github') return false;
return forge.authenticated === true ? true : forge.authenticated === false ? false : null;
}
return null;
};
const emptyReviewerSummary = (status = 'unknown') => ({
configured: 0,
available: 0,
unavailable: 0,
unknown: 0,
status,
});
const summarizeReviewers = (entries) => {
const summary = emptyReviewerSummary(entries.length ? 'unknown' : 'not-configured');
summary.configured = entries.length;
if (!entries.length) return summary;
entries.forEach((entry) => {
if (entry.available === true) summary.available += 1;
else if (entry.available === false) summary.unavailable += 1;
else summary.unknown += 1;
});
summary.status = summary.unavailable > 0 ? 'unavailable' : summary.unknown > 0 ? 'unknown' : 'ready';
return summary;
};
const reviewerProbeFor = (dependencies) => {
let promise;
return () => {
if (!promise) {
promise = Promise.all([
dependencies.getCodeReviewDefaults().catch(() => null),
dependencies.getReviewerCliInstalled().catch(() => null),
]);
}
return promise;
};
};
const inspectReviewers = async (forge, dependencies, reviewerProbe = reviewerProbeFor(dependencies)) => {
const [defaults, installed] = await reviewerProbe();
if (!defaults) {
return {
configured: null,
required: emptyReviewerSummary(),
optional: emptyReviewerSummary(),
status: 'unknown',
};
}
const fixedReviewers = Array.isArray(defaults.reviewers) ? defaults.reviewers.filter((value) => isReviewer(value)) : [];
const usernames = Array.isArray(defaults.usernames) ? defaults.usernames.filter((value) => typeof value === 'string' && value.trim()) : [];
const optional = new Set(Array.isArray(defaults.optionalReviewers) ? defaults.optionalReviewers : []);
const requiredEntries = fixedReviewers
.filter((reviewer) => !optional.has(reviewer))
.map((reviewer) => ({ available: reviewerAvailability(reviewer, forge, installed) }));
const optionalEntries = fixedReviewers
.filter((reviewer) => optional.has(reviewer))
.map((reviewer) => ({ available: reviewerAvailability(reviewer, forge, installed) }));
const usernameAvailability = forge?.authenticated === true ? true : forge?.authenticated === false ? false : null;
usernames.forEach((username) => {
const identity = `@${username.replace(/^@/, '')}`;
const entry = { available: usernameAvailability };
if (optional.has(identity)) optionalEntries.push(entry);
else requiredEntries.push(entry);
});
const required = summarizeReviewers(requiredEntries);
const optionalSummary = summarizeReviewers(optionalEntries);
return {
configured: required.configured + optionalSummary.configured,
required,
optional: optionalSummary,
status: required.status === 'unavailable'
? 'unavailable'
: required.status === 'unknown'
? 'unknown'
: optionalSummary.status === 'unavailable' || optionalSummary.status === 'unknown' ? 'degraded' : 'ready',
};
};
const engineStatus = (workspaces) => workspaces.flatMap((workspace) => [
workspace.engines?.node?.status,
workspace.engines?.packageManager?.status,
]).filter(Boolean);
const dependencyStatus = (workspaces) => workspaces.map((workspace) => workspace.dependencies?.status).filter(Boolean);
// A repository without package.json may be a native app. A missing manifest
// in a declared child workspace is still an incomplete Node workspace.
const isNonNodeRepository = (workspaces) => workspaces?.length === 1
&& workspaces[0].id === 'root' && workspaces[0].manifest === 'missing';
const checkStatus = (preflight, check) => {
if (['dependencies', 'engines'].includes(check)
&& preflight?.workspaceDiscovery === 'ready'
&& isNonNodeRepository(preflight.workspaces)) return 'ready';
if (check === 'dependencies') {
const statuses = dependencyStatus(Array.isArray(preflight?.workspaces) ? preflight.workspaces : []);
if (preflight?.workspaceDiscovery !== 'ready' || !statuses.length) return 'unknown';
return statuses.some((status) => status === 'unknown') ? 'unknown' : statuses.some((status) => status !== 'installed') ? 'unavailable' : 'ready';
}
if (check === 'engines') {
const statuses = engineStatus(Array.isArray(preflight?.workspaces) ? preflight.workspaces : []).filter((status) => status !== 'not-declared');
if (preflight?.workspaceDiscovery !== 'ready' || !Array.isArray(preflight?.workspaces) || !preflight.workspaces.every((workspace) => workspace.manifest === 'ready')) return 'unknown';
return statuses.some((status) => status === 'unknown') ? 'unknown' : statuses.some((status) => status === 'incompatible') ? 'unavailable' : 'ready';
}
if (check === 'submodules') {
if (preflight?.submodules?.status === 'not-configured') return 'ready';
return preflight?.submodules?.status === 'initialized' ? 'ready' : preflight?.submodules?.status === 'uninitialized' ? 'unavailable' : 'unknown';
}
if (check === 'forge') return ['ready', 'not-configured'].includes(preflight?.forge?.status) ? 'ready' : preflight?.forge?.status === 'unavailable' ? 'unavailable' : 'unknown';
if (check === 'reviewers') return ['ready', 'not-configured'].includes(preflight?.reviewers?.required?.status) ? 'ready' : preflight?.reviewers?.required?.status === 'unavailable' ? 'unavailable' : 'unknown';
return 'unknown';
};
const CHECK_MESSAGES = Object.freeze({
dependencies: 'Dependencies are absent or could not be verified for a declared workspace.',
engines: 'The required Node.js or package-manager engine is incompatible or could not be verified.',
submodules: 'One or more configured submodules are not initialized or could not be verified.',
forge: 'The configured forge CLI is unavailable or is not authenticated.',
reviewers: 'One or more required reviewers are unavailable or could not be verified.',
});
const buildWarnings = (preflight) => {
const warnings = [];
if (preflight.checkout?.state === 'dirty') {
warnings.push({
code: 'workspace-checkout-dirty',
check: 'checkout',
severity: 'advisory',
message: 'The workspace has local changes; delegated work should preserve them.',
});
}
PERSISTENT_MIND_VALIDATION_CHECKS.forEach((check) => {
const status = checkStatus(preflight, check);
if (status !== 'ready') warnings.push({ code: `workspace-${check}-${status}`, check, severity: 'warning', message: CHECK_MESSAGES[check] });
});
if (preflight.reviewers.optional.status === 'unavailable' || preflight.reviewers.optional.status === 'unknown') {
warnings.push({
code: `workspace-reviewers-optional-${preflight.reviewers.optional.status}`,
check: 'reviewers',
severity: 'advisory',
message: 'Optional reviewers are unavailable or could not be verified; they do not block the task.',
});
}
if (preflight.truncated) warnings.push({ code: 'workspace-preflight-truncated', check: 'preflight', severity: 'advisory', message: 'Workspace preflight reached a safety bound; some facts may be unknown.' });
return warnings;
};
const readinessForSnapshot = (repository, checkout, workspaces, submodules, forge, reviewers) => {
if (repository.reachable === false) return 'blocked';
const nodeWorkspaces = isNonNodeRepository(workspaces) ? [] : workspaces;
if (nodeWorkspaces.some((workspace) => workspace.manifest !== 'ready')) return 'unknown';
const engines = engineStatus(nodeWorkspaces);
if (engines.includes('incompatible')) return 'blocked';
if (repository.reachable === null || checkout.state === 'unknown' || engines.includes('unknown')) return 'unknown';
const degraded = checkout.state === 'dirty'
|| dependencyStatus(nodeWorkspaces).some((status) => status !== 'installed')
|| submodules.status === 'uninitialized'
|| submodules.status === 'unknown'
|| forge.status === 'unavailable'
|| forge.status === 'unknown'
|| ['unavailable', 'unknown'].includes(reviewers.required.status)
|| ['unavailable', 'unknown'].includes(reviewers.optional.status);
return degraded ? 'degraded' : 'ready';
};
const unknownSnapshot = (app, capturedAt) => ({
schemaVersion: PERSISTENT_MIND_WORKSPACE_PREFLIGHT_SCHEMA_VERSION,
capturedAt,
freshness: { state: 'fresh', capturedAt, ageMs: 0, ttlMs: PERSISTENT_MIND_WORKSPACE_PREFLIGHT_TTL_MS },
truncated: false,
workspaceDiscovery: 'unknown',
readiness: 'unknown',
repository: { configured: Boolean(typeof app?.repoPath === 'string' && app.repoPath.trim()), reachable: null },
checkout: { state: 'unknown' },
workspaces: [],
submodules: { configured: null, status: 'unknown', initialized: null },
forge: { provider: 'unknown', cli: null, installed: null, authenticated: null, status: 'unknown' },
reviewers: { configured: null, required: emptyReviewerSummary(), optional: emptyReviewerSummary(), status: 'unknown' },
warnings: [{ code: 'workspace-preflight-unknown', check: 'preflight', severity: 'warning', message: 'Workspace readiness could not be verified.' }],
});
const collectPreflight = async (app, options) => {
const dependencies = { ...defaultDependencies, ...(options.dependencies || {}) };
const reviewerProbe = options.reviewerProbe || reviewerProbeFor(dependencies);
const timestamp = nowValue(options.now);
const capturedAt = new Date(timestamp).toISOString();
const repoPath = typeof app?.repoPath === 'string' ? app.repoPath.trim() : '';
const normalizedApp = repoPath ? { ...app, repoPath } : app;
const repository = await inspectRepository(normalizedApp, dependencies);
if (repository.repository.reachable !== true) {
const submodules = { configured: null, status: 'unknown', initialized: null };
const forge = await inspectForge(normalizedApp, repository.repository, dependencies);
const reviewers = await inspectReviewers(forge, dependencies, reviewerProbe);
const snapshot = {
schemaVersion: PERSISTENT_MIND_WORKSPACE_PREFLIGHT_SCHEMA_VERSION,
capturedAt,
freshness: { state: 'fresh', capturedAt, ageMs: 0, ttlMs: PERSISTENT_MIND_WORKSPACE_PREFLIGHT_TTL_MS },
truncated: false,
workspaceDiscovery: 'unknown',
readiness: repository.repository.reachable === false ? 'blocked' : 'unknown',
repository: repository.repository,
checkout: repository.checkout,
workspaces: [],
submodules,
forge,
reviewers,
warnings: [],
};
snapshot.warnings = buildWarnings(snapshot);
return snapshot;
}
const rootManifest = await readPackageManifest(join(repoPath, 'package.json'), dependencies);
const discovered = await discoverWorkspacePaths(repoPath, rootManifest.value, dependencies);
const workspacePaths = discovered.paths.slice(0, PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxWorkspaces);
const managerNames = new Set();
const manifests = await Promise.all(workspacePaths.map((workspacePath) => (
workspacePath === repoPath ? Promise.resolve(rootManifest) : readPackageManifest(join(workspacePath, 'package.json'), dependencies)
)));
const workspaceFacts = manifests.map((manifest, index) => {
const workspacePath = workspacePaths[index];
const requirements = engineRequirements(manifest.value);
if (requirements.packageManager?.name) managerNames.add(requirements.packageManager.name);
return { workspacePath, manifest, requirements };
});
const managerVersions = await readManagerVersions(managerNames, repoPath, dependencies, options.runtime || {});
const nodeVersion = options.runtime?.nodeVersion || process.versions.node || null;
const workspaces = await Promise.all(workspaceFacts.map(async ({ workspacePath, manifest, requirements }) => {
const manager = requirements.packageManager;
return {
id: relativeWorkspaceId(repoPath, workspacePath),
manifest: manifest.state,
lockfile: await inspectLockfile(workspacePath, repoPath, dependencies),
dependencies: await inspectDependencies(workspacePath, repoPath, dependencies),
engines: {
node: compatibility(nodeVersion, requirements.node),
packageManager: manager ? {
name: manager.name,
...compatibility(managerVersions[manager.name], manager.required),
} : null,
},
scripts: scriptNames(manifest.value),
};
}));
const submodules = await inspectSubmodules(repoPath, dependencies);
const forge = await inspectForge(normalizedApp, repository.repository, dependencies);
const reviewers = await inspectReviewers(forge, dependencies, reviewerProbe);
const snapshot = {
schemaVersion: PERSISTENT_MIND_WORKSPACE_PREFLIGHT_SCHEMA_VERSION,
capturedAt,
freshness: { state: 'fresh', capturedAt, ageMs: 0, ttlMs: PERSISTENT_MIND_WORKSPACE_PREFLIGHT_TTL_MS },
truncated: discovered.truncated || workspaceFacts.some(({ manifest }) => manifest.state === 'truncated'),
workspaceDiscovery: discovered.unknown ? 'unknown' : discovered.truncated ? 'truncated' : 'ready',
readiness: null,
repository: repository.repository,
checkout: repository.checkout,
workspaces,
submodules,
forge,
reviewers,
warnings: [],
};
snapshot.readiness = discovered.unknown || discovered.truncated
? 'unknown'
: readinessForSnapshot(repository.repository, repository.checkout, workspaces, submodules, forge, reviewers);
snapshot.warnings = buildWarnings(snapshot);
return snapshot;
};
const cacheKeyFor = (app) => `${app?.id || ''}\0${app?.repoPath || ''}\0${app?.workTracker || 'auto'}`;
const withFreshness = (snapshot, timestamp) => {
const captured = Date.parse(snapshot.capturedAt);
const ageMs = Number.isFinite(captured) ? Math.max(0, timestamp - captured) : null;
return {
...snapshot,
freshness: {
state: ageMs !== null && ageMs <= PERSISTENT_MIND_WORKSPACE_PREFLIGHT_TTL_MS ? 'fresh' : 'stale',
capturedAt: snapshot.capturedAt,
ageMs,
ttlMs: PERSISTENT_MIND_WORKSPACE_PREFLIGHT_TTL_MS,
},
};
};
/** Clear the process-local cache; intended for tests and explicit diagnostics. */
export function resetPersistentMindWorkspacePreflightCache() {
cache.clear();
}
/**
* Inspect one configured app. A repeated read within the freshness window does
* not re-run git, filesystem, forge, or reviewer probes.
*/
export function readPersistentMindWorkspacePreflight(app, {
force = false,
now = Date.now,
dependencies,
runtime,
reviewerProbe,
} = {}) {
const timestamp = nowValue(now);
const key = cacheKeyFor(app);
const cached = cache.get(key);
if (!force && cached && cached.expiresAt > timestamp) {
return cached.promise.then((snapshot) => withFreshness(snapshot, timestamp));
}
const promise = collectPreflight(app, { now: timestamp, dependencies, runtime, reviewerProbe })
.catch(() => unknownSnapshot(app, new Date(timestamp).toISOString()));
cache.set(key, { promise, expiresAt: timestamp + PERSISTENT_MIND_WORKSPACE_PREFLIGHT_TTL_MS });
return promise.then((snapshot) => withFreshness(snapshot, timestamp));
}
/** Read a bounded set of app preflights, retaining app identity but no paths. */
export async function readPersistentMindWorkspacePreflights(apps, options = {}) {
const candidates = (Array.isArray(apps) ? apps : [])
.filter((app) => typeof app?.id === 'string' && app.id.trim()
&& !isPathLike(app.id.trim())
&& app.id.length <= PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxAppIdChars)
.slice(0, PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxApps);
const dependencies = { ...defaultDependencies, ...(options.dependencies || {}) };
const reviewerProbe = reviewerProbeFor(dependencies);
return Promise.all(candidates.map(async (app) => ({
appId: app.id.trim(),
appName: typeof app.name === 'string' && app.name.trim() && !isPathLike(app.name.trim())
? app.name.trim().slice(0, PERSISTENT_MIND_WORKSPACE_PREFLIGHT_LIMITS.maxAppNameChars)
: app.id.trim(),
preflight: await readPersistentMindWorkspacePreflight(app, {
...options,
dependencies,
reviewerProbe,
}),
})));
}
/**
* Apply task-declared validation requirements to a cached preflight. Missing
* dependencies remain advisory for tasks that do not declare them, so a
* docs-only/read-only task is not incorrectly blocked.
*/
export function assessPersistentMindWorkspaceReadiness(preflight, requiredValidation = []) {
const required = [...new Set((Array.isArray(requiredValidation) ? requiredValidation : [])
.filter((check) => PERSISTENT_MIND_VALIDATION_CHECKS.includes(check)))];
const blockers = required
.map((check) => ({ check, status: checkStatus(preflight || {}, check) }))
.filter(({ status }) => status !== 'ready')
.map(({ check, status }) => ({
code: `workspace-${check}-${status}`,
check,
status,
message: CHECK_MESSAGES[check],
}));
const readiness = blockers.length > 0
? 'blocked'
: preflight?.readiness || 'unknown';
return {
readiness,
requiredValidation: required,
blockers,
warnings: Array.isArray(preflight?.warnings) ? preflight.warnings : [],
};
}
export const PERSISTENT_MIND_WORKSPACE_PREFLIGHT_CHECKS = PERSISTENT_MIND_VALIDATION_CHECKS;