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
import { appListQuerySchema, appQualityQuerySchema, appQualityHistoryQuerySchema, appQualityFederationQuerySchema } from '../../lib/auditQuality.js';
import { exportPortosQuality } from '../../services/appQualityFederation.js';
import { enrichAppsWithQuality, getAppQualityHistory } from '../../services/appQuality.js';
import { getAppLaneHealth } from '../../services/appLaneHealth.js';
import { publishAppQualitySnapshot } from '../../services/appQualitySnapshotFile.js';
/**
* App CRUD + status enrichment + archive lifecycle.
*
* GET / → App[] (PM2-status-enriched)
* GET /:id → App (PM2-status-enriched, + appVersion)
* POST / → App
* PUT /:id → App (ports written back to ecosystem config)
* DELETE /:id → 204 (removes the PortOS registry association only)
* POST /:id/archive → App
* POST /:id/unarchive → App
* POST /:id/quality-snapshot → commits the app's `.quality.json` snapshot
*/
import { Router } from 'express';
import { existsSync } from 'fs';
import { join } from 'path';
import { readJSONFile } from '../../lib/fileUtils.js';
import * as appsService from '../../services/apps.js';
import { notifyAppsChanged, PORTOS_APP_ID } from '../../services/apps.js';
import * as pm2Service from '../../services/pm2.js';
import { validateRequest, appSchema, appUpdateSchema } from '../../lib/validation.js';
import { asyncHandler, ServerError } from '../../lib/errorHandler.js';
import { usesPm2 } from '../../services/appProcessTypes.js';
import { detectAppIcon } from '../../services/appIconDetect.js';
import { hasDeployScript } from '../../services/appDeployer.js';
import { checkScripts } from '../../services/xcodeScripts.js';
import { applyEcosystemPortEdits } from '../../services/appPortConfig.js';
import { isRepo } from '../../services/git.js';
import { enrichAppsWithPm2Status } from '../../services/appListEnrichment.js';
import { loadApp, pathExists, deriveAppPorts, computeOverallStatus } from './shared.js';
const router = Router();
// Lets the task form disable worktree/PR for a non-git app before submit (the
// create route refuses it with NOT_A_GIT_REPO). Left undefined — i.e. unknown,
// not "not a repo" — when the directory is missing, mirroring that route.
async function withGitRepoFlag(app) {
if (!app.repoPath || !existsSync(app.repoPath)) return app;
return { ...app, isGitRepo: await isRepo(app.repoPath) };
}
// Numeric local evidence only. This endpoint never invokes aggregate reads or forwards peer data.
router.get('/quality-federation', asyncHandler(async (req, res) => {
const { days, repository, categories } = validateRequest(appQualityFederationQuerySchema, req.query);
const payload = await exportPortosQuality(req.get('X-PortOS-Instance-Id'), days, {}, repository, categories);
if (!payload) throw new ServerError('Quality sharing requires a registered enabled sync peer and a known repository', {
status: 403,
code: 'PEER_PULL_FORBIDDEN',
severity: 'warning',
});
res.json(payload);
}));
// GET /api/apps - List all apps. The bare response is the frozen PM2-enriched
// peer-probe contract. `view=nav` is the cheap sidebar projection; `view=probe`
// keeps PM2 enrichment but returns only the fields the peer UI consumes.
router.get('/', asyncHandler(async (req, res) => {
const { includeQuality, view } = validateRequest(appListQuerySchema, req.query);
const rawApps = await appsService.getAllApps();
if (view === 'nav') {
res.json(rawApps.map(({ id, name, icon, archived, type }) => ({ id, name, icon, archived, type })));
return;
}
const apps = await Promise.all((await enrichAppsWithPm2Status(rawApps)).map(withGitRepoFlag));
if (view === 'probe') {
res.json(apps.map(({ id, name, icon, overallStatus, uiPort, apiPort, type }) => ({
id, name, icon, overallStatus, uiPort, apiPort, type,
})));
return;
}
// The bare list is the frozen peer-probe contract. Local UI opts into
// assessment prose explicitly so it never rides automatic federation probes.
res.json(includeQuality === 'true' ? await enrichAppsWithQuality(apps) : apps);
}));
router.get('/:id/quality-history', loadApp, asyncHandler(async (req, res) => {
const { days } = validateRequest(appQualityHistoryQuerySchema, req.query);
res.json(await getAppQualityHistory(req.loadedApp, days));
}));
// GET /api/apps/:id/lane-health - What became of each audit lane's filed issues
// (#12088): a forge read on request, never cached into the app record.
router.get('/:id/lane-health', loadApp, asyncHandler(async (req, res) => {
res.json(await getAppLaneHealth(req.loadedApp));
}));
// POST /api/apps/:id/quality-snapshot - Land this app's numeric snapshot as
// `.quality.json` through an immediately-merged PR. Deliberately NOT gated on
// publishQualitySnapshot: the toggle automates the audit hook, a manual call
// here is explicit intent.
router.post('/:id/quality-snapshot', loadApp, asyncHandler(async (req, res) => {
res.json({ success: true, ...await publishAppQualitySnapshot(req.loadedApp) });
}));
// GET /api/apps/:id - Get single app
router.get('/:id', loadApp, asyncHandler(async (req, res) => {
const app = req.loadedApp;
const { includeQuality } = validateRequest(appQualityQuerySchema, req.query);
// Non-PM2 apps skip PM2 status
let statuses = {};
let overallStatus = 'n/a';
let degraded = false;
if (usesPm2(app.type)) {
// getAppStatusStrict returns `null` when the PM2 read failed (vs a real
// status object). A failed read is genuinely unknown, not "not running" —
// mark `degraded` so the detail UI can offer refresh-to-retry rather than a
// misleading Start. Mirrors the list endpoint's `degraded`.
// Read each process's PM2 status in parallel — a detail view of a
// multi-process app would otherwise serialize one IPC round-trip per process.
const reads = await Promise.all(
(app.pm2ProcessNames || []).map(async (processName) => ({
processName,
status: await pm2Service.getAppStatusStrict(processName, app.pm2Home),
})),
);
for (const { processName, status } of reads) {
if (status === null) {
degraded = true;
statuses[processName] = { name: processName, status: 'unknown', pm2_env: null };
} else {
statuses[processName] = status;
}
}
// Compute overall status (same logic as list endpoint). A degraded read
// short-circuits to `unknown` rather than collapsing to `not_started`.
overallStatus = computeOverallStatus(Object.values(statuses), degraded);
}
// Auto-derive uiPort/apiPort/devUiPort from processes when not explicitly set
const { uiPort, apiPort, devUiPort } = deriveAppPorts(app, app.processes || []);
// Read version from app's package.json if available, and flag whether the
// repo declares git submodules — the detail view only shows its Submodules
// tab for repos that actually have any.
let appVersion = null;
let hasSubmodules = false;
if (app.repoPath) {
const [pkg, gitmodules] = await Promise.all([
readJSONFile(join(app.repoPath, 'package.json'), null, { logError: false }),
pathExists(join(app.repoPath, '.gitmodules')),
]);
appVersion = pkg?.version || null;
hasSubmodules = gitmodules;
}
// The detail read alone scans the checkout for applicability (cached per repo),
// so the Quality tab's denominator and runner skip audits that cannot apply.
const [enrichedApp] = includeQuality === 'true'
? await enrichAppsWithQuality([app], {
resolveApplicability: async (target) => (await import('../../services/appQualitySchedule.js')).inapplicableAuditReasons(target),
})
: [app];
res.json({ ...enrichedApp, uiPort, devUiPort, apiPort, overallStatus, degraded, pm2Status: statuses, appVersion, hasSubmodules, hasDeployScript: hasDeployScript(app), xcodeScripts: checkScripts(app) });
}));
// POST /api/apps - Create new app
router.post('/', asyncHandler(async (req, res, next) => {
const data = validateRequest(appSchema, req.body);
// Detect app icon before creation to avoid a double write
if (data.repoPath) {
const detectedIcon = await detectAppIcon(data.repoPath, data.type);
if (detectedIcon) data.appIconPath = detectedIcon;
}
const app = await appsService.createApp(data);
notifyAppsChanged('create', app.id);
res.status(201).json(app);
}));
// PUT /api/apps/:id - Update app
router.put('/:id', asyncHandler(async (req, res, next) => {
const data = validateRequest(appUpdateSchema, req.body);
// Only port edits need the canonical-config write-back; snapshot the
// pre-update app just for those so ordinary updates (rename, archive,
// jira/datadog) don't pay the extra read + fs stat. tlsPort is omitted: it's
// synthetic (derived from cert presence / upgradeAppTls), never a literal in
// ecosystem.config.cjs, so there's nothing to rewrite for it.
const PORT_KEYS = ['apiPort', 'uiPort', 'devUiPort'];
const hasPortUpdate = PORT_KEYS.some(key => key in data);
const existing = hasPortUpdate ? await appsService.getAppById(req.params.id) : null;
// Port fields in apps.json are *derived* from ecosystem.config.cjs (the source
// of truth PM2 reads). Persist the change to the canonical config FIRST,
// before the derived registry: an unreadable/unwritable config then surfaces
// as a failed request instead of a 200 that leaves apps.json and PM2
// disagreeing (the write throws and bubbles to the error middleware).
if (existing && usesPm2(existing.type) && await pathExists(existing.repoPath)) {
const { persistFailed, uiPortOverride, portCollision } = await applyEcosystemPortEdits(existing, data);
// Pin the stored uiPort to the derived value for served-by-API apps. This
// both overwrites the drawer's echoed/stale UI field and keeps the stored
// value tracking apiPort — deleting `data.uiPort` would NOT be enough, since
// updateApp merges omitted fields over the existing record, so a stale
// explicit `uiPort` would survive (truthy) and block re-derivation. Writing
// the derived value self-corrects on every save.
if (uiPortOverride !== undefined) {
data.uiPort = uiPortOverride;
}
// Collision gate: the edit would give one process a port another process in
// the same ecosystem config already holds. Nothing was written; reject so the
// user fixes the conflict rather than discovering it as a failed PM2 restart.
if (portCollision) {
throw new ServerError(
`Port ${portCollision.newPort} is already used by the ${portCollision.heldBy} process (${portCollision.heldLabel}) in ${existing.name}'s ecosystem config — pick a port no other process claims.`,
{ status: 422, code: 'PORT_COLLISION' }
);
}
// Honesty gate: if the user changed a port we could NOT write to the
// source-of-truth config, reject the whole update rather than persist a
// registry value PM2 will contradict (and the next refresh will revert).
if (persistFailed) {
throw new ServerError(
`Could not persist port change to ${existing.name}'s ecosystem config — the port is derived from process config or is not a literal value. Edit the ecosystem.config.cjs directly to change this port.`,
{ status: 422, code: 'PORT_NOT_PERSISTABLE' }
);
}
}
// layeredIntelligence must go through the dedicated merge helper — the generic
// updateApp shallow-REPLACES the nested object, so a partial patch like
// { layeredIntelligence: { enabled: true } } would wipe stored sources /
// allowedScopes / providerId / lastRunAt. Pull it out, apply the rest, then
// merge-apply the config so untouched fields are preserved.
const { layeredIntelligence: liUpdate, ...rest } = data;
const app = await appsService.updateApp(req.params.id, rest);
if (!app) {
throw new ServerError('App not found', { status: 404, code: 'NOT_FOUND' });
}
if (liUpdate !== undefined) {
const merged = await appsService.updateAppLayeredIntelligence(req.params.id, liUpdate);
notifyAppsChanged('update', req.params.id);
res.json(merged || app);
return;
}
notifyAppsChanged('update', req.params.id);
res.json(app);
}));
// DELETE /api/apps/:id - Delete app (PortOS baseline cannot be deleted)
router.delete('/:id', asyncHandler(async (req, res, next) => {
if (req.params.id === PORTOS_APP_ID) {
throw new ServerError('PortOS baseline app cannot be deleted', { status: 403, code: 'PROTECTED' });
}
const deleted = await appsService.deleteApp(req.params.id);
if (!deleted) {
throw new ServerError('App not found', { status: 404, code: 'NOT_FOUND' });
}
// Keep the dashboard, sidebar, OpenWorld, and any open detail view in sync
// with the registry removal. This only removes PortOS's association; the
// app's repository is not touched by appsService.deleteApp().
notifyAppsChanged('delete', req.params.id);
res.status(204).send();
}));
// POST /api/apps/:id/archive - Archive app (exclude from COS tasks)
router.post('/:id/archive', asyncHandler(async (req, res) => {
if (req.params.id === PORTOS_APP_ID) {
throw new ServerError('PortOS baseline app cannot be archived', { status: 403, code: 'PROTECTED' });
}
const app = await appsService.archiveApp(req.params.id);
if (!app) {
throw new ServerError('App not found', { status: 404, code: 'NOT_FOUND' });
}
console.log(`📦 Archived app: ${app.name}`);
notifyAppsChanged('archive', app.id);
res.json(app);
}));
// POST /api/apps/:id/unarchive - Unarchive app (include in COS tasks)
router.post('/:id/unarchive', asyncHandler(async (req, res) => {
const app = await appsService.unarchiveApp(req.params.id);
if (!app) {
throw new ServerError('App not found', { status: 404, code: 'NOT_FOUND' });
}
console.log(`📤 Unarchived app: ${app.name}`);
notifyAppsChanged('unarchive', app.id);
res.json(app);
}));
export default router;