@assistkick/create 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistkick/create",
-  "version": "1.2.0",
+  "version": "1.4.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",
     "test": "tsx --test tests/**/*.test.ts"
   },
   "devDependencies": {

package/templates/assistkick-product-system/GITHUB_APP_SETUP.md

@@ -0,0 +1,88 @@
+# GitHub App Setup Guide
+
+This guide walks you through creating a GitHub App and configuring it for use with AssistKick.
+
+## Step 1: Create the GitHub App
+
+1. Go to **GitHub Settings > Developer settings > GitHub Apps** (or navigate to `https://github.com/settings/apps`)
+2. Click **New GitHub App**
+3. Fill in the form:
+
+| Field               | Value                                          |
+|---------------------|------------------------------------------------|
+| **GitHub App name** | Something unique, e.g. `assistkick-<your-org>` |
+| **Homepage URL**    | Your AssistKick instance URL (or any URL)      |
+| **Webhook**         | Uncheck "Active" (webhooks are not needed)     |
+
+### Permissions
+
+Under **Repository permissions**, grant the following:
+
+| Permission   | Access                    |
+|--------------|---------------------------|
+| **Contents** | Read & write              |
+| **Metadata** | Read-only (auto-selected) |
+
+You can add more permissions later if needed (e.g. Pull requests, Issues).
+
+### Installation access
+
+Under **Where can this GitHub App be installed?**, choose:
+- **Only on this account** — if you only need it for your own repos/org
+- **Any account** — if multiple orgs will install it
+
+1. Click **Create GitHub App**
+
+## Step 2: Generate a Private Key
+
+1. After creating the app, you'll be on the app's settings page
+2. Scroll down to **Private keys**
+3. Click **Generate a private key**
+4. A `.pem` file will be downloaded — keep this safe
+5. **Convert to PKCS#8 and base64-encode** (required — GitHub generates PKCS#1 keys but the backend uses the `jose` library which requires PKCS#8):
+
+```bash
+openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in your-app-name.pem | base64
+```
+
+Use the base64 output as the `GITHUB_APP_PRIVATE_KEY` environment variable in Step 5.
+
+## Step 3: Note Your App ID
+
+On the app's settings page, find the **App ID** near the top (it's a numeric value like `123456`).
+
+## Step 4: Install the App
+
+1. From the app's settings page, click **Install App** in the left sidebar
+2. Choose the organization or account where you want to install it
+3. Select **All repositories** or pick specific repos
+4. Click **Install**
+
+## Step 5: Configure Environment Variables
+
+Set these two environment variables where AssistKick runs:
+
+```bash
+GITHUB_APP_ID=123456
+GITHUB_APP_PRIVATE_KEY=LS0tLS1CRUdJTi...
+```
+
+The value is the base64-encoded PKCS#8 key from Step 2. The backend auto-detects whether the key is raw PEM or base64-encoded.
+
+## Step 6: Verify
+
+1. Open your project in AssistKick
+2. Open the **Git Repository** dialog
+3. Go to the **GitHub** tab
+4. Click **Test Connection**
+5. You should see your installations listed — select one, pick a repo, and connect
+
+## Troubleshooting
+
+| Problem                     | Solution                                                                                                                          |
+|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| "GitHub App not configured" | `GITHUB_APP_ID` or `GITHUB_APP_PRIVATE_KEY` is missing from env                                                                   |
+| "No installations found"    | Install the app on your GitHub account/org (Step 4)                                                                               |
+| 401 / "Bad credentials"     | Private key doesn't match the App ID, or the key is malformed                                                                     |
+| "pkcs8" must be PKCS#8      | Key is in PKCS#1 format — convert it with `openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in key.pem -out key-pkcs8.pem` |
+| No repos listed             | The installation doesn't have access to any repos — edit installation permissions on GitHub                                       |

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) => {