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
/**
* GSD (Get Stuff Done) API Routes
*
* Mounted at /api/cos/gsd
* Provides endpoints for scanning, analyzing, and acting on GSD project state.
*/
import { Router } from 'express'
import { z } from 'zod'
import { existsSync } from 'fs'
import { readFile } from 'fs/promises'
import { asyncHandler, ServerError } from '../lib/errorHandler.js'
import { atomicWrite } from '../lib/fileUtils.js'
import { documentUpdateSchema, validateRequest } from '../lib/validation.js'
import * as gsdService from '../services/gsdService.js'
import { resolveGsdPath } from '../services/gsdPaths.js'
import { addTask } from '../services/cosTaskStore.js'
import { getActiveApps } from '../services/apps.js'
import * as git from '../services/git.js'
const router = Router()
// Validation schemas
const concernIdsSchema = z.object({
concernIds: z.array(z.string()).optional(),
all: z.boolean().optional()
}).refine(data => data.all || (data.concernIds && data.concernIds.length > 0), {
message: 'Either concernIds or all:true is required'
})
const phaseActionSchema = z.object({
action: z.enum(['plan', 'execute', 'verify'])
})
const GSD_ALLOWED_DOCUMENTS = ['PROJECT.md', 'ROADMAP.md', 'STATE.md', 'CONCERNS.md', 'RETROSPECTIVE.md', 'MILESTONES.md']
const GSD_ACTION_DESCRIPTIONS = {
plan: (phaseId) => `Run /gsd:plan-phase to create a detailed plan for phase ${phaseId}`,
execute: (phaseId) => `Run /gsd:execute-phase to execute phase ${phaseId}`,
verify: (phaseId) => `Run /gsd:verify-work to verify phase ${phaseId} implementation`
}
/**
* Load app and resolve .planning path, attach to req
*/
async function loadAppPlanning(req) {
const apps = await getActiveApps()
const app = apps.find(a => a.id === req.params.appId)
if (!app?.repoPath) return null
const planningPath = await resolveGsdPath(app.repoPath, '', 'dir')
if (!planningPath || !existsSync(planningPath)) return null
return { app, planningPath }
}
// GET /projects — list GSD-enabled projects
router.get('/projects', asyncHandler(async (req, res) => {
const projects = await gsdService.scanForGsdProjects()
res.json({ projects })
}))
// GET /projects/:appId — project detail
router.get('/projects/:appId', asyncHandler(async (req, res) => {
const project = await gsdService.getGsdProject(req.params.appId)
if (!project) {
throw new ServerError('GSD project not found', { status: 404, code: 'GSD_PROJECT_NOT_FOUND' })
}
res.json(project)
}))
// GET /projects/:appId/concerns — parsed CONCERNS.md with severity
router.get('/projects/:appId/concerns', asyncHandler(async (req, res) => {
const project = await gsdService.getGsdProject(req.params.appId)
if (!project) {
throw new ServerError('GSD project not found', { status: 404, code: 'GSD_PROJECT_NOT_FOUND' })
}
res.json({ concerns: project.concerns })
}))
// GET /projects/:appId/phases — phase list with status
router.get('/projects/:appId/phases', asyncHandler(async (req, res) => {
const project = await gsdService.getGsdProject(req.params.appId)
if (!project) {
throw new ServerError('GSD project not found', { status: 404, code: 'GSD_PROJECT_NOT_FOUND' })
}
const pendingActions = await gsdService.getGsdPendingActions(req.params.appId)
res.json({ phases: project.phases, pendingActions })
}))
// GET /projects/:appId/phases/:phaseId — phase detail
router.get('/projects/:appId/phases/:phaseId', asyncHandler(async (req, res) => {
const project = await gsdService.getGsdProject(req.params.appId)
if (!project) {
throw new ServerError('GSD project not found', { status: 404, code: 'GSD_PROJECT_NOT_FOUND' })
}
const phase = project.phases.find(p => p.id === req.params.phaseId)
if (!phase) {
throw new ServerError('Phase not found', { status: 404, code: 'GSD_PHASE_NOT_FOUND' })
}
res.json(phase)
}))
// POST /projects/:appId/concerns/tasks — create CoS tasks from selected concerns
router.post('/projects/:appId/concerns/tasks', asyncHandler(async (req, res) => {
const body = validateRequest(concernIdsSchema, req.body)
const allTasks = await gsdService.generateConcernTasks(req.params.appId)
if (allTasks.length === 0) {
throw new ServerError('No concerns found for this project', { status: 404, code: 'NO_CONCERNS' })
}
const tasksToCreate = body.all
? allTasks
: allTasks.filter(t => body.concernIds.includes(t.metadata.gsdConcern))
const created = []
for (const task of tasksToCreate) {
const result = await addTask(task, 'internal')
created.push(result)
}
console.log(`📋 Created ${created.length} CoS tasks from GSD concerns for ${req.params.appId}`)
res.json({ created: created.length, tasks: created })
}))
// POST /projects/:appId/phases/:phaseId/action — trigger plan/execute/verify as CoS task
router.post('/projects/:appId/phases/:phaseId/action', asyncHandler(async (req, res) => {
const { action } = validateRequest(phaseActionSchema, req.body)
const { appId, phaseId } = req.params
const project = await gsdService.getGsdProject(appId)
if (!project) {
throw new ServerError('GSD project not found', { status: 404, code: 'GSD_PROJECT_NOT_FOUND' })
}
const phase = project.phases.find(p => p.id === phaseId)
if (!phase) {
throw new ServerError('Phase not found', { status: 404, code: 'GSD_PHASE_NOT_FOUND' })
}
const description = GSD_ACTION_DESCRIPTIONS[action](phaseId)
const result = await addTask({
description,
app: appId,
priority: 'MEDIUM',
metadata: { gsdPhase: phaseId, gsdAction: action }
}, 'internal')
console.log(`🎯 GSD ${action} task created for ${appId} phase ${phaseId}`)
res.json({ success: true, task: result })
}))
// GET /projects/:appId/documents/:docName — read a .planning/ document
router.get('/projects/:appId/documents/:docName', asyncHandler(async (req, res) => {
const { docName } = req.params
if (!GSD_ALLOWED_DOCUMENTS.includes(docName)) {
throw new ServerError('Document not in allowlist', { status: 400, code: 'INVALID_DOCUMENT' })
}
const ctx = await loadAppPlanning(req)
if (!ctx) {
throw new ServerError('GSD project not found', { status: 404, code: 'GSD_PROJECT_NOT_FOUND' })
}
const resolved = await resolveGsdPath(ctx.app.repoPath, docName)
if (!existsSync(resolved)) {
throw new ServerError('Document not found', { status: 404, code: 'NOT_FOUND' })
}
const content = await readFile(resolved, 'utf-8')
res.json({ filename: docName, content })
}))
// PUT /projects/:appId/documents/:docName — save and git commit a .planning/ document
router.put('/projects/:appId/documents/:docName', asyncHandler(async (req, res) => {
const { docName } = req.params
if (!GSD_ALLOWED_DOCUMENTS.includes(docName)) {
throw new ServerError('Document not in allowlist', { status: 400, code: 'INVALID_DOCUMENT' })
}
const ctx = await loadAppPlanning(req)
if (!ctx) {
throw new ServerError('GSD project not found', { status: 404, code: 'GSD_PROJECT_NOT_FOUND' })
}
const resolved = await resolveGsdPath(ctx.app.repoPath, docName)
const { content, commitMessage } = validateRequest(documentUpdateSchema, req.body)
const created = !existsSync(resolved)
await atomicWrite(resolved, content)
const relPath = `.planning/${docName}`
await git.stageFiles(ctx.app.repoPath, [relPath])
const status = await git.getStatus(ctx.app.repoPath)
if (status.clean) {
return res.json({ success: true, noChanges: true })
}
const message = commitMessage || `docs: update .planning/${docName} via PortOS`
const result = await git.commit(ctx.app.repoPath, message)
console.log(`📝 ${created ? 'Created' : 'Updated'} .planning/${docName} in ${ctx.app.name} (${result.hash})`)
res.json({ success: true, hash: result.hash, created })
}))
export default router