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
/**
* App document endpoints — browse/read/write the markdown a managed app keeps
* in its repo, and commit edits back through git.
*
* GET /:id/documents → { documents, docs, hasPlanning, gsd }
* GET /:id/documents/*docPath → { filename, content }
* PUT /:id/documents/*docPath → { success, hash?, created } (git commit)
*
* The browsable set is a RULE, not a fixed allowlist (#5773): every markdown
* file in the repo root, plus everything under a `docs/` directory when the app
* has one. `SUGGESTED_DOCUMENTS` only seeds the "create this file" affordance
* for the conventional agent-facing docs a repo may be missing.
*/
import { Router } from 'express';
import { readdir, readFile, realpath } from 'fs/promises';
import { dirname, join } from 'path';
import { atomicWrite, listDirectoryByExtension } from '../../lib/fileUtils.js';
import { isGitStageableFilePath } from '../../lib/gitArgs.js';
import { isPathInsideDir, isSafeFilename, isTopLevelEntryName } from '../../lib/pathSafety.js';
import { documentUpdateSchema, validateRequest } from '../../lib/validation.js';
import { asyncHandler, ServerError } from '../../lib/errorHandler.js';
import * as git from '../../services/git.js';
import { loadApp, pathExists } from './shared.js';
const router = Router();
// Offered as "Create <file>" when absent from the repo root. Both agent-instruction
// names are listed (#4852): AGENTS.md is canonical, while a managed app's CLAUDE.md
// is either its one-line AGENTS.md bridge or its only file. PLAN.md stays here
// because it is a selectable work tracker for apps with no forge issue tracker.
const SUGGESTED_DOCUMENTS = ['AGENTS.md', 'CLAUDE.md', 'GOALS.md', 'PLAN.md', 'REVIEW.md', 'REJECTED.md'];
// Renderable text extensions. A docs/ tree also holds images and data files;
// those are skipped rather than handed to a markdown renderer as mojibake.
const DOC_EXTENSIONS = ['.md', '.markdown', '.mdx', '.txt'];
const DOCS_DIR = 'docs';
const MAX_DOCS_DEPTH = 5; // directory levels walked below the repo root
const MAX_DOCS_FILES = 500; // guard against a pathological docs tree
const isDocFile = (name) => isSafeFilename(name, DOC_EXTENSIONS);
const byPath = (a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' });
/**
* Every renderable file under `docs/`, as repo-relative `docs/...` paths.
* Skips dot-directories, and symlinks fall out on their own — `withFileTypes`
* reports them as neither a file nor a directory.
*/
async function listDocsTree(repoPath) {
const found = [];
const walk = async (relDir, depth) => {
if (depth > MAX_DOCS_DEPTH || found.length >= MAX_DOCS_FILES) return;
const entries = await readdir(join(repoPath, relDir), { withFileTypes: true }).catch(() => []);
for (const entry of entries) {
if (found.length >= MAX_DOCS_FILES) return;
if (entry.name.startsWith('.') || !isTopLevelEntryName(entry.name)) continue;
const rel = `${relDir}/${entry.name}`;
if (entry.isDirectory()) await walk(rel, depth + 1);
else if (entry.isFile() && isDocFile(entry.name)) found.push(rel);
}
};
if (await pathExists(join(repoPath, DOCS_DIR))) await walk(DOCS_DIR, 1);
return found.sort(byPath);
}
/**
* Shape check for a requested document path: a renderable file that is either
* at the repo root or somewhere under `docs/`. `isSafeFilename` covers the leaf
* (null bytes, separators, `.`/`..`, extension); the directory segments get the
* same traversal rule via `isTopLevelEntryName`.
*/
function isAllowedDocumentPath(rel) {
const parts = String(rel || '').split('/');
const leaf = parts.pop();
if (!isDocFile(leaf)) return false;
if (parts.length === 0) return true;
if (parts[0] !== DOCS_DIR || parts.length > MAX_DOCS_DEPTH) return false;
return parts.every(isTopLevelEntryName);
}
/**
* Validate `*docPath` and resolve it inside the app's repo. Throws the same
* 400s the single-file allowlist used to, so client error handling is unchanged.
*
* The containment check runs TWICE, and the second pass is what makes it real:
* `isPathInsideDir` is lexical, so a symlinked directory component inside the
* repo (`docs/shared -> /outside`) passes the string comparison while `readFile`
* and `atomicWrite` happily follow the link. Canonicalizing closes that escape.
* The old six-name allowlist had no directory component to subvert; the wildcard
* route does, so the canonical check arrived with it.
*/
async function resolveDocumentPath(app, docPath) {
const filename = Array.isArray(docPath) ? docPath.join('/') : String(docPath || '');
if (!isAllowedDocumentPath(filename)) {
throw new ServerError('Document not in allowlist', { status: 400, code: 'INVALID_DOCUMENT' });
}
const resolved = join(app.repoPath, filename);
const traversal = () =>
new ServerError('Invalid document path', { status: 400, code: 'PATH_TRAVERSAL' });
if (!isPathInsideDir(app.repoPath, resolved)) throw traversal();
// The PARENT must canonically live in the repo (so a not-yet-created file
// still validates), and so must the file itself when it already exists — the
// leaf can be a symlink even when every directory above it is real.
const realRoot = await realpath(app.repoPath);
const realParent = await realpath(dirname(resolved)).catch(() => null);
if (!realParent || (realParent !== realRoot && !isPathInsideDir(realRoot, realParent))) {
throw traversal();
}
const realFile = await realpath(resolved).catch(() => null);
if (realFile && !isPathInsideDir(realRoot, realFile)) throw traversal();
return { filename, resolved };
}
/** 400s when the app has no usable checkout — shared by the read/write routes. */
async function requireRepoPath(app) {
if (!app.repoPath || !await pathExists(app.repoPath)) {
throw new ServerError('App repo path does not exist', { status: 400, code: 'PATH_NOT_FOUND' });
}
}
// GET /api/apps/:id/documents - List root markdown + the docs/ tree
router.get('/:id/documents', loadApp, asyncHandler(async (req, res) => {
const app = req.loadedApp;
if (!app.repoPath || !await pathExists(app.repoPath)) {
return res.json({ documents: [], docs: [], hasPlanning: false });
}
const [rootNames, docs] = await Promise.all([
listDirectoryByExtension(app.repoPath, { extensions: DOC_EXTENSIONS, mapEntry: name => name }),
listDocsTree(app.repoPath),
]);
const rootDocs = rootNames.sort(byPath);
const documents = [
...rootDocs.map(filename => ({ filename, exists: true })),
...SUGGESTED_DOCUMENTS.filter(f => !rootDocs.includes(f)).map(filename => ({ filename, exists: false })),
];
const planningDir = join(app.repoPath, '.planning');
const hasPlanning = await pathExists(planningDir);
// GSD status: detect which GSD artifacts exist
const gsd = {
hasCodebaseMap: await pathExists(join(planningDir, 'codebase')),
hasProject: await pathExists(join(planningDir, 'PROJECT.md')),
hasRoadmap: await pathExists(join(planningDir, 'ROADMAP.md')),
hasState: await pathExists(join(planningDir, 'STATE.md')),
hasConcerns: await pathExists(join(planningDir, 'CONCERNS.md')),
};
res.json({ documents, docs, hasPlanning, gsd });
}));
// GET /api/apps/:id/documents/*docPath - Read a single document
router.get('/:id/documents/*docPath', loadApp, asyncHandler(async (req, res) => {
const app = req.loadedApp;
await requireRepoPath(app);
const { filename, resolved } = await resolveDocumentPath(app, req.params.docPath);
if (!await pathExists(resolved)) {
throw new ServerError('Document not found', { status: 404, code: 'NOT_FOUND' });
}
const content = await readFile(resolved, 'utf-8');
res.json({ filename, content });
}));
// PUT /api/apps/:id/documents/*docPath - Update a document and git commit
router.put('/:id/documents/*docPath', loadApp, asyncHandler(async (req, res) => {
const app = req.loadedApp;
await requireRepoPath(app);
const { filename, resolved } = await resolveDocumentPath(app, req.params.docPath);
// Git staging rejects a substring `..` and shell metacharacters, which
// `isSafeFilename` allows (`docs/notes..md` is a legal filename). Refuse the
// write up front rather than mutating the file and then 500-ing on the commit.
if (!isGitStageableFilePath(filename)) {
throw new ServerError('Document name cannot be committed by git', {
status: 400, code: 'INVALID_DOCUMENT'
});
}
const { content, commitMessage } = validateRequest(documentUpdateSchema, req.body);
const created = !await pathExists(resolved);
await atomicWrite(resolved, content);
await git.stageFiles(app.repoPath, [filename]);
// Scope the check to this document, because the commit below is scoped too:
// a repo-wide `clean` is false whenever the user has any unrelated dirty file,
// and the partial commit that follows then exits 1 on an unchanged document.
const status = await git.getStatus(app.repoPath, { paths: [filename] });
if (status.clean) {
return res.json({ success: true, noChanges: true });
}
const message = commitMessage || `docs: update ${filename} via PortOS`;
// Scope the commit to this document: the user may have staged unrelated work
// in their checkout, and a doc edit must never sweep it into this commit.
const result = await git.commit(app.repoPath, message, { paths: [filename] });
console.log(`📝 ${created ? 'Created' : 'Updated'} ${filename} in ${app.name} (${result.hash})`);
res.json({ success: true, hash: result.hash, created });
}));
export default router;