@assistkick/create 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistkick/create",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Scaffold assistkick-product-system into any project",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
     "build": "tsc",
     "prepare_templates": "bash scripts/prepare_templates.sh",
     "prepublishOnly": "bash scripts/prepare_templates.sh && pnpm build",
+    "publish": "npm publish --access public",
     "test": "tsx --test tests/**/*.test.ts"
   },
   "devDependencies": {

package/templates/assistkick-product-system/packages/backend/src/routes/git.ts

@@ -0,0 +1,231 @@
+/**
+ * Git repository routes — connect/manage git repos for projects.
+ * POST   /api/projects/:id/git/connect       — connect a git repo (clone URL + GitHub App)
+ * POST   /api/projects/:id/git/init           — initialize a new local git repo
+ * POST   /api/projects/:id/git/disconnect     — disconnect a git repo
+ * GET    /api/projects/:id/git/status         — get git repo status
+ * POST   /api/projects/:id/git/test           — test GitHub App connection
+ * GET    /api/projects/:id/git/installations  — list GitHub App installations
+ * GET    /api/projects/:id/git/repos          — list repos for an installation
+ */
+
+import { Router } from 'express';
+import type { ProjectService } from '../services/project_service.js';
+import type { GitHubAppService } from '../services/github_app_service.js';
+import type { ProjectWorkspaceService } from '../services/project_workspace_service.js';
+
+interface GitRoutesDeps {
+  projectService: ProjectService;
+  githubAppService: GitHubAppService;
+  workspaceService: ProjectWorkspaceService;
+  log: (tag: string, ...args: any[]) => void;
+}
+
+export const createGitRoutes = ({ projectService, githubAppService, workspaceService, log }: GitRoutesDeps): Router => {
+  const router: Router = Router({ mergeParams: true });
+
+  // POST /api/projects/:id/git/connect — connect a git repo
+  router.post('/connect', async (req, res) => {
+    const { id } = req.params;
+    const { repoUrl, githubInstallationId, githubRepoFullName, baseBranch } = req.body;
+    log('GIT', `POST /api/projects/${id}/git/connect repoUrl="${repoUrl}"`);
+
+    if (!repoUrl && !githubRepoFullName) {
+      res.status(400).json({ error: 'Either repoUrl or githubRepoFullName is required' });
+      return;
+    }
+
+    try {
+      const project = await projectService.getById(id);
+      if (!project) {
+        res.status(404).json({ error: 'Project not found' });
+        return;
+      }
+
+      // Determine clone URL
+      let cloneUrl = repoUrl;
+      if (!cloneUrl && githubRepoFullName) {
+        if (githubInstallationId && githubAppService.isConfigured()) {
+          cloneUrl = await githubAppService.buildAuthenticatedCloneUrl(githubInstallationId, githubRepoFullName);
+        } else {
+          cloneUrl = `https://github.com/${githubRepoFullName}.git`;
+        }
+      }
+
+      // Clone the repo into the workspace
+      await workspaceService.cloneRepo(id, cloneUrl);
+
+      // Detect default branch
+      const detectedBranch = await workspaceService.getDefaultBranch(id);
+      const effectiveBranch = baseBranch || detectedBranch;
+
+      // Save repo metadata to project
+      const updated = await projectService.connectRepo(id, {
+        repoUrl: githubRepoFullName ? `https://github.com/${githubRepoFullName}.git` : repoUrl,
+        githubInstallationId,
+        githubRepoFullName,
+        baseBranch: effectiveBranch,
+      });
+
+      res.json({ project: updated });
+    } catch (err: any) {
+      log('GIT', `Connect repo failed: ${err.message}`);
+      res.status(500).json({ error: `Failed to connect repo: ${err.message}` });
+    }
+  });
+
+  // POST /api/projects/:id/git/init — initialize a new local git repo
+  router.post('/init', async (req, res) => {
+    const { id } = req.params;
+    log('GIT', `POST /api/projects/${id}/git/init`);
+
+    try {
+      const project = await projectService.getById(id);
+      if (!project) {
+        res.status(404).json({ error: 'Project not found' });
+        return;
+      }
+
+      await workspaceService.initWorkspace(id);
+      const branch = await workspaceService.getDefaultBranch(id);
+
+      // Update project with base branch (no remote URL since it's local only)
+      const updated = await projectService.connectRepo(id, {
+        repoUrl: '',
+        baseBranch: branch,
+      });
+
+      res.json({ project: updated });
+    } catch (err: any) {
+      log('GIT', `Init repo failed: ${err.message}`);
+      res.status(500).json({ error: `Failed to initialize repo: ${err.message}` });
+    }
+  });
+
+  // POST /api/projects/:id/git/disconnect — disconnect a git repo
+  router.post('/disconnect', async (req, res) => {
+    const { id } = req.params;
+    log('GIT', `POST /api/projects/${id}/git/disconnect`);
+
+    try {
+      const updated = await projectService.disconnectRepo(id);
+      res.json({ project: updated });
+    } catch (err: any) {
+      log('GIT', `Disconnect repo failed: ${err.message}`);
+      if (err.message === 'Project not found') {
+        res.status(404).json({ error: err.message });
+        return;
+      }
+      res.status(500).json({ error: `Failed to disconnect repo: ${err.message}` });
+    }
+  });
+
+  // GET /api/projects/:id/git/status — get git repo status
+  router.get('/status', async (req, res) => {
+    const { id } = req.params;
+
+    try {
+      const project = await projectService.getById(id);
+      if (!project) {
+        res.status(404).json({ error: 'Project not found' });
+        return;
+      }
+
+      const gitStatus = await workspaceService.getStatus(id);
+      res.json({
+        ...gitStatus,
+        repoUrl: project.repoUrl,
+        githubInstallationId: project.githubInstallationId,
+        githubRepoFullName: project.githubRepoFullName,
+        baseBranch: project.baseBranch,
+        githubAppConfigured: githubAppService.isConfigured(),
+      });
+    } catch (err: any) {
+      log('GIT', `Get git status failed: ${err.message}`);
+      res.status(500).json({ error: `Failed to get git status: ${err.message}` });
+    }
+  });
+
+  // POST /api/projects/:id/git/test — test GitHub App connection
+  router.post('/test', async (req, res) => {
+    const { id } = req.params;
+    log('GIT', `POST /api/projects/${id}/git/test`);
+
+    try {
+      if (!githubAppService.isConfigured()) {
+        res.json({
+          configured: false,
+          error: 'GitHub App credentials not configured (GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY)',
+        });
+        return;
+      }
+
+      const installations = await githubAppService.listInstallations();
+      res.json({
+        configured: true,
+        installations: installations.map(i => ({
+          id: i.id,
+          account: i.account.login,
+          accountType: i.account.type,
+        })),
+      });
+    } catch (err: any) {
+      log('GIT', `Test GitHub App connection failed: ${err.message}`);
+      res.json({
+        configured: true,
+        error: `Connection test failed: ${err.message}`,
+      });
+    }
+  });
+
+  // GET /api/projects/:id/git/installations — list GitHub App installations
+  router.get('/installations', async (_req, res) => {
+    try {
+      if (!githubAppService.isConfigured()) {
+        res.json({ installations: [], configured: false });
+        return;
+      }
+
+      const installations = await githubAppService.listInstallations();
+      res.json({
+        configured: true,
+        installations: installations.map(i => ({
+          id: i.id,
+          account: i.account.login,
+          accountType: i.account.type,
+        })),
+      });
+    } catch (err: any) {
+      log('GIT', `List installations failed: ${err.message}`);
+      res.status(500).json({ error: `Failed to list installations: ${err.message}` });
+    }
+  });
+
+  // GET /api/projects/:id/git/repos?installation_id=xxx — list repos for an installation
+  router.get('/repos', async (req, res) => {
+    const installationId = req.query.installation_id as string;
+
+    if (!installationId) {
+      res.status(400).json({ error: 'installation_id query parameter is required' });
+      return;
+    }
+
+    try {
+      const repos = await githubAppService.listInstallationRepos(installationId);
+      res.json({
+        repos: repos.map(r => ({
+          id: r.id,
+          fullName: r.full_name,
+          private: r.private,
+          defaultBranch: r.default_branch,
+          cloneUrl: r.clone_url,
+        })),
+      });
+    } catch (err: any) {
+      log('GIT', `List repos failed: ${err.message}`);
+      res.status(500).json({ error: `Failed to list repos: ${err.message}` });
+    }
+  });
+
+  return router;
+};

package/templates/assistkick-product-system/packages/backend/src/routes/kanban.ts

@@ -10,7 +10,7 @@ import { log, pipeline } from '../services/init.js';
 
 const router: Router = Router();
 
-const VALID_COLUMNS = ['todo', 'in_progress', 'in_review', 'qa', 'done'];
+const VALID_COLUMNS = ['backlog', 'todo', 'in_progress', 'in_review', 'qa', 'done'];
 
 // GET /api/kanban
 router.get('/', async (req, res) => {
@@ -19,20 +19,20 @@ router.get('/', async (req, res) => {
   try {
     const kanban = await loadKanban(projectId);
 
-    // Auto-add missing feature nodes to the TODO column
+    // Auto-add missing feature nodes to the Backlog column
     const graph = await readGraph(projectId);
     const featureNodes = graph.nodes.filter((n: any) => n.type === 'feature');
     for (const node of featureNodes) {
       if (!kanban[node.id]) {
         const newEntry = {
-          column: 'todo',
+          column: 'backlog',
           rejection_count: 0,
           notes: [],
           moved_at: node.created_at || new Date().toISOString(),
         };
         await saveKanbanEntry(node.id, newEntry, projectId);
         kanban[node.id] = newEntry;
-        log('KANBAN', `Auto-added ${node.id} to todo`);
+        log('KANBAN', `Auto-added ${node.id} to backlog`);
       }
     }
 

package/templates/assistkick-product-system/packages/backend/src/routes/pipeline.ts

@@ -1,9 +1,9 @@
 /**
- * Pipeline API routes — start/status/unblock dev pipeline.
+ * Pipeline API routes — start/status/unblock dev pipeline + orchestrator.
  */
 
 import { Router } from 'express';
-import { log, pipeline } from '../services/init.js';
+import { log, pipeline, orchestrator } from '../services/init.js';
 
 const router: Router = Router();
 
@@ -26,6 +26,18 @@ router.get('/:id/pipeline', async (req, res) => {
   res.json(result);
 });
 
+// POST /api/kanban/:id/resume
+router.post('/:id/resume', async (req, res) => {
+  const featureId = req.params.id;
+  try {
+    const result = await pipeline.resume(featureId);
+    res.status(result.status).json(result.error ? { error: result.error } : { resumed: result.resumed, feature_id: result.feature_id });
+  } catch (err: any) {
+    log('RESUME', `UNEXPECTED ERROR: ${err.message}`);
+    res.status(500).json({ error: err.message });
+  }
+});
+
 // POST /api/kanban/:id/unblock
 router.post('/:id/unblock', async (req, res) => {
   const featureId = req.params.id;
@@ -38,4 +50,39 @@ router.post('/:id/unblock', async (req, res) => {
   }
 });
 
+// --- Orchestrator (Play All) endpoints ---
+
+// POST /api/pipeline/play-all
+router.post('/play-all', async (req, res) => {
+  const projectId = req.query.project_id as string | undefined;
+  try {
+    const result = orchestrator.startPlayAll(projectId);
+    const resolved = await result;
+    res.status(resolved.status).json(
+      resolved.error ? { error: resolved.error } : { started: resolved.started }
+    );
+  } catch (err: any) {
+    log('ORCHESTRATOR', `UNEXPECTED ERROR: ${err.message}`);
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// POST /api/pipeline/stop-all
+router.post('/stop-all', (_req, res) => {
+  try {
+    const result = orchestrator.stopPlayAll();
+    res.status(result.status).json(
+      result.error ? { error: result.error } : { stopped: result.stopped }
+    );
+  } catch (err: any) {
+    log('ORCHESTRATOR', `UNEXPECTED ERROR: ${err.message}`);
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// GET /api/pipeline/orchestrator-status
+router.get('/orchestrator-status', (_req, res) => {
+  res.json(orchestrator.getStatus());
+});
+
 export default router;

package/templates/assistkick-product-system/packages/backend/src/routes/terminal.ts

@@ -0,0 +1,82 @@
+/**
+ * Terminal session routes — REST API for managing named PTY sessions.
+ * GET    /api/terminal/sessions           — list all active sessions
+ * POST   /api/terminal/sessions           — create a new named session
+ * DELETE /api/terminal/sessions/:id       — kill and remove a session
+ *
+ * Admin-only: all routes require admin role.
+ */
+
+import { Router } from 'express';
+import type { Request, Response } from 'express';
+import type { PtySessionManager } from '../services/pty_session_manager.js';
+
+interface TerminalRoutesDeps {
+  ptyManager: PtySessionManager;
+  log: (tag: string, ...args: unknown[]) => void;
+}
+
+const requireAdmin = (req: Request, res: Response, next: () => void): void => {
+  const user = (req as any).user;
+  if (!user || user.role !== 'admin') {
+    res.status(403).json({ error: 'Admin privileges required' });
+    return;
+  }
+  next();
+};
+
+export const createTerminalRoutes = ({ ptyManager, log }: TerminalRoutesDeps): Router => {
+  const router: Router = Router();
+
+  router.use(requireAdmin as any);
+
+  // GET /api/terminal/sessions
+  router.get('/sessions', (_req, res) => {
+    const sessions = ptyManager.listSessions();
+    res.json({ sessions });
+  });
+
+  // POST /api/terminal/sessions
+  router.post('/sessions', (req, res) => {
+    const { projectId, projectName } = req.body;
+
+    if (!projectId || typeof projectId !== 'string') {
+      res.status(400).json({ error: 'projectId is required' });
+      return;
+    }
+    if (!projectName || typeof projectName !== 'string') {
+      res.status(400).json({ error: 'projectName is required' });
+      return;
+    }
+
+    const session = ptyManager.createSession(projectId.trim(), projectName.trim(), 80, 24);
+    log('TERMINAL', `Created session "${session.name}" for project ${projectId}`);
+    res.status(201).json({
+      session: {
+        id: session.id,
+        name: session.name,
+        projectId: session.projectId,
+        projectName: session.projectName,
+        state: session.state,
+        createdAt: session.createdAt.toISOString(),
+      },
+    });
+  });
+
+  // DELETE /api/terminal/sessions/:id
+  router.delete('/sessions/:id', (req, res) => {
+    const { id } = req.params;
+    const session = ptyManager.getSession(id);
+
+    if (!session) {
+      res.status(404).json({ error: 'Session not found' });
+      return;
+    }
+
+    ptyManager.destroySession(id);
+    log('TERMINAL', `Killed session ${id}`);
+    res.json({ ok: true });
+  });
+
+  return router;
+};

package/templates/assistkick-product-system/packages/backend/src/server.ts

@@ -16,7 +16,7 @@ import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
 import { WebSocketServer } from 'ws';
 import * as pty from 'node-pty';
-import { initServices, log } from './services/init.js';
+import { initServices, log, githubAppService, workspaceService } from './services/init.js';
 import { AuthService } from './services/auth_service.js';
 import { EmailService } from './services/email_service.js';
 import { PasswordResetService } from './services/password_reset_service.js';
@@ -29,11 +29,13 @@ import { AuthMiddleware } from './middleware/auth_middleware.js';
 import { createAuthRoutes } from './routes/auth.js';
 import { createUserRoutes } from './routes/users.js';
 import { createProjectRoutes } from './routes/projects.js';
+import { createTerminalRoutes } from './routes/terminal.js';
 import { getDb } from '@assistkick/shared/lib/db.js';
 import graphRoutes from './routes/graph.js';
 import kanbanRoutes from './routes/kanban.js';
 import pipelineRoutes from './routes/pipeline.js';
 import coherenceRoutes from './routes/coherence.js';
+import { createGitRoutes } from './routes/git.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_PORT = parseInt(process.env.PORT || '3000', 10);
@@ -68,8 +70,8 @@ app.use((req, res, next) => {
   const start = Date.now();
   res.on('finish', () => {
     const duration = Date.now() - start;
-    // Skip noisy pipeline polls
-    if (req.originalUrl.endsWith('/pipeline')) return;
+    // Skip noisy pipeline and orchestrator status polls
+    if (req.originalUrl.endsWith('/pipeline') || req.originalUrl.endsWith('/orchestrator-status')) return;
     log('HTTP', `${req.method} ${req.originalUrl} ${res.statusCode} ${duration}ms`);
   });
   next();
@@ -101,15 +103,29 @@ const projectService = new ProjectService({ getDb, log });
 const projectRoutes = createProjectRoutes({ projectService, log });
 app.use('/api/projects', authMiddleware.requireAuth, projectRoutes);
 
+// Git repository routes (nested under /api/projects/:id/git)
+const gitRoutes = createGitRoutes({ projectService, githubAppService, workspaceService, log });
+app.use('/api/projects/:id/git', authMiddleware.requireAuth, gitRoutes);
+
 // Ensure default project exists and assign orphan nodes on startup
 projectService.ensureDefaultAndAssignOrphans().catch((err: any) => {
   log('STARTUP', `Failed to ensure default project: ${err.message}`);
 });
 
+// PTY session manager — initialized early so terminal REST routes can reference it
+// Resolve project root: from packages/backend/src → assistkick-product-system → repo root
+const PROJECT_ROOT = join(__dirname, '..', '..', '..', '..');
+const ptyManager = new PtySessionManager({ spawn: pty.spawn, log, projectRoot: PROJECT_ROOT });
+
+// Terminal session management REST routes (admin-only, auth required)
+const terminalRoutes = createTerminalRoutes({ ptyManager, log });
+app.use('/api/terminal', authMiddleware.requireAuth, terminalRoutes);
+
 // Protected API routes — require authentication
 app.use('/api', authMiddleware.requireAuth, graphRoutes);
 app.use('/api/kanban', authMiddleware.requireAuth, kanbanRoutes);
 app.use('/api/kanban', authMiddleware.requireAuth, pipelineRoutes);
+app.use('/api/pipeline', authMiddleware.requireAuth, pipelineRoutes);
 app.use('/api/coherence', authMiddleware.requireAuth, coherenceRoutes);
 
 // Redirect favicon.ico to SVG favicon served from static files
@@ -130,9 +146,6 @@ const server = createServer(app);
 
 // Set up WebSocket for terminal
 const wss = new WebSocketServer({ noServer: true });
-// Resolve project root: from packages/backend/src → assistkick-product-system → repo root
-const PROJECT_ROOT = join(__dirname, '..', '..', '..', '..');
-const ptyManager = new PtySessionManager({ spawn: pty.spawn, log, projectRoot: PROJECT_ROOT });
 const terminalHandler = new TerminalWsHandler({ wss, authService, ptyManager, log });
 
 server.on('upgrade', (req, socket, head) => {

package/templates/assistkick-product-system/packages/backend/src/services/github_app_service.ts

@@ -0,0 +1,146 @@
+/**
+ * GitHubAppService — generates installation access tokens for GitHub App authentication.
+ * Uses env vars GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY.
+ * Tokens are short-lived (1 hour) and scoped to a specific installation.
+ */
+
+import { SignJWT, importPKCS8 } from 'jose';
+
+interface GitHubAppServiceDeps {
+  log: (tag: string, ...args: any[]) => void;
+}
+
+interface Installation {
+  id: number;
+  account: { login: string; type: string };
+  app_id: number;
+  target_type: string;
+}
+
+interface InstallationRepo {
+  id: number;
+  full_name: string;
+  private: boolean;
+  default_branch: string;
+  clone_url: string;
+}
+
+export class GitHubAppService {
+  private readonly log: (tag: string, ...args: any[]) => void;
+
+  constructor({ log }: GitHubAppServiceDeps) {
+    this.log = log;
+  }
+
+  private getAppId = (): string => {
+    const appId = process.env.GITHUB_APP_ID;
+    if (!appId) throw new Error('GITHUB_APP_ID environment variable is not set');
+    return appId;
+  };
+
+  private getPrivateKey = (): string => {
+    const key = process.env.GITHUB_APP_PRIVATE_KEY;
+    if (!key) throw new Error('GITHUB_APP_PRIVATE_KEY environment variable is not set');
+    // Support both raw PEM and base64-encoded PEM (for env vars that can't contain newlines)
+    if (key.startsWith('-----BEGIN')) return key;
+    return Buffer.from(key, 'base64').toString('utf-8');
+  };
+
+  /** Check whether GitHub App credentials are configured. */
+  isConfigured = (): boolean => {
+    return !!(process.env.GITHUB_APP_ID && process.env.GITHUB_APP_PRIVATE_KEY);
+  };
+
+  /** Generate a JWT signed with the App's private key (valid for 10 minutes). */
+  private generateJwt = async (): Promise<string> => {
+    const appId = this.getAppId();
+    const privateKeyPem = this.getPrivateKey();
+    const privateKey = await importPKCS8(privateKeyPem, 'RS256');
+
+    const now = Math.floor(Date.now() / 1000);
+    const jwt = await new SignJWT({})
+      .setProtectedHeader({ alg: 'RS256' })
+      .setIssuer(appId)
+      .setIssuedAt(now - 60) // clock skew tolerance
+      .setExpirationTime(now + 600) // 10 minutes
+      .sign(privateKey);
+
+    return jwt;
+  };
+
+  /** Get a short-lived installation access token for git operations. */
+  getInstallationToken = async (installationId: string): Promise<string> => {
+    const jwt = await this.generateJwt();
+    this.log('GITHUB', `Requesting installation token for installation ${installationId}`);
+
+    const resp = await fetch(`https://api.github.com/app/installations/${installationId}/access_tokens`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${jwt}`,
+        'Accept': 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+      },
+    });
+
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new Error(`GitHub API error (${resp.status}): ${body}`);
+    }
+
+    const data = await resp.json();
+    this.log('GITHUB', `Installation token obtained, expires at ${data.expires_at}`);
+    return data.token;
+  };
+
+  /** List all installations of this GitHub App. */
+  listInstallations = async (): Promise<Installation[]> => {
+    const jwt = await this.generateJwt();
+
+    const resp = await fetch('https://api.github.com/app/installations', {
+      headers: {
+        'Authorization': `Bearer ${jwt}`,
+        'Accept': 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+      },
+    });
+
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new Error(`GitHub API error (${resp.status}): ${body}`);
+    }
+
+    return resp.json();
+  };
+
+  /** List repositories accessible to a specific installation. */
+  listInstallationRepos = async (installationId: string): Promise<InstallationRepo[]> => {
+    const token = await this.getInstallationToken(installationId);
+
+    const resp = await fetch('https://api.github.com/installation/repositories?per_page=100', {
+      headers: {
+        'Authorization': `token ${token}`,
+        'Accept': 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+      },
+    });
+
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new Error(`GitHub API error (${resp.status}): ${body}`);
+    }
+
+    const data = await resp.json();
+    return data.repositories;
+  };
+
+  /** Build an authenticated clone URL using an installation token. */
+  buildAuthenticatedCloneUrl = async (installationId: string, repoFullName: string): Promise<string> => {
+    const token = await this.getInstallationToken(installationId);
+    return `https://x-access-token:${token}@github.com/${repoFullName}.git`;
+  };
+
+  /** Configure git credential helper for a workspace to use installation tokens. */
+  buildGitCredentialUrl = (token: string, repoFullName: string): string => {
+    return `https://x-access-token:${token}@github.com/${repoFullName}.git`;
+  };
+}