@worca/ui 0.41.0 → 0.42.0

package/server/templates-routes.js

@@ -39,9 +39,10 @@ import {
 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { Router } from 'express';
+import { raw as expressRaw, Router } from 'express';
 import { atomicWriteSync } from './atomic-write.js';
 import { templatesDir } from './paths.js';
+import { buildPromptsModel } from './template-prompts.js';
 
 /**
  * Match template IDs: lowercase alphanumeric, hyphens, and underscores,
@@ -52,15 +53,26 @@ import { templatesDir } from './paths.js';
 const TEMPLATE_RE = /^[a-z0-9_-]{1,64}$/;
 const TIERS = ['project', 'user', 'builtin'];
 const MUTABLE_TIERS = ['project', 'user'];
+const _OVERLAY_NAME_RE = /^[a-z0-9._-]{1,64}\.(md|block\.md)$/;
 export { TEMPLATE_RE, TIERS };
 
 function isValidTier(tier) {
   return TIERS.includes(tier);
 }
-function isMutableTier(tier) {
+function _isMutableTier(tier) {
   return MUTABLE_TIERS.includes(tier);
 }
 
+function hasOverlays(tmplDir) {
+  const agentsDir = join(tmplDir, 'agents');
+  if (!existsSync(agentsDir)) return false;
+  try {
+    return readdirSync(agentsDir).some((f) => _OVERLAY_NAME_RE.test(f));
+  } catch {
+    return false;
+  }
+}
+
 function readTemplateJson(dirPath) {
   const manifestPath = join(dirPath, 'template.json');
   if (!existsSync(manifestPath)) return null;
@@ -112,6 +124,7 @@ function listTemplatesFlat(projectRoot) {
       const manifest = readTemplateJson(join(dir, entry.name));
       if (!manifest) continue;
       const id = manifest.id || entry.name;
+      const tmplDir = join(dir, entry.name);
       out.push({
         tier,
         id,
@@ -122,6 +135,7 @@ function listTemplatesFlat(projectRoot) {
         tags: manifest.tags || [],
         created_at: manifest.created_at,
         builtin: manifest.builtin === true || tier === 'builtin',
+        has_overlays: hasOverlays(tmplDir),
       });
     }
   }
@@ -190,6 +204,8 @@ function runWorcaTemplates(projectRoot, args, opts = {}) {
       combined.includes('invalid')
     ) {
       code = 'validation_error';
+    } else if (combined.includes('partial_rename')) {
+      code = 'partial_rename';
     }
     const e = new Error(stderr.trim() || err.message || 'worca CLI failed');
     e.cliCode = code;
@@ -281,26 +297,137 @@ function duplicateTemplateViaCli(projectRoot, srcId, dstId, dstTier) {
   ]);
 }
 
-function exportBundle(projectRoot, id) {
+/**
+ * Export a template bundle. Returns `{ json, data }` where `json` is
+ * true for JSON bundles (data is parsed object) and false for zip bundles
+ * (data is raw Buffer with filename in `filename`).
+ *
+ * `mode` is 'standalone' (default — self-contained config + resolved prompts)
+ * or 'delta' (sparse overlay). Standalone materialises a prompt set even when
+ * the template has no on-disk overlays, so the CLI may emit a zip in cases the
+ * old on-disk `hasOverlays` check would have missed. We therefore sniff the
+ * produced file's magic bytes instead of predicting the format.
+ */
+function exportBundle(projectRoot, id, mode = 'standalone') {
+  const normalizedMode = mode === 'delta' ? 'delta' : 'standalone';
   const dir = mkdtempSync(join(tmpdir(), 'worca-bundle-'));
-  const bundlePath = join(dir, `${id}.json`);
   try {
+    const bundlePath = join(dir, `${id}-bundle.out`);
     runWorcaTemplates(projectRoot, [
       'export',
       '--to',
       bundlePath,
       '--templates',
       id,
+      '--mode',
+      normalizedMode,
     ]);
     if (existsSync(bundlePath)) {
-      return JSON.parse(readFileSync(bundlePath, 'utf8'));
+      const buf = readFileSync(bundlePath);
+      // ZIP local-file-header magic: 'PK\x03\x04'.
+      const isZip =
+        buf.length >= 4 &&
+        buf[0] === 0x50 &&
+        buf[1] === 0x4b &&
+        buf[2] === 0x03 &&
+        buf[3] === 0x04;
+      if (isZip) {
+        return { json: false, filename: `${id}-bundle.zip`, data: buf };
+      }
+      return { json: true, data: JSON.parse(buf.toString('utf8')) };
     }
-    return { templates: [{ id }] };
+    return { json: true, data: { templates: [{ id }] } };
   } finally {
     cleanupTemp(dir);
   }
 }
 
+/**
+ * Export a single template to a (secret) GitHub gist via the CLI and return the
+ * gist URL. Delegates to `worca templates export --to gist`, which shells out to
+ * `gh gist create` and prints the URL on stdout. Throws (via runWorcaTemplates)
+ * with the CLI stderr as the message when gh is unavailable or gist creation
+ * fails — the caller maps that to a JSON error. Gist export only supports
+ * overlay-free templates (the CLI rejects overlays); the UI hides the button
+ * for templates with overlays, matching that constraint.
+ */
+function exportGist(projectRoot, id) {
+  const stdout = runWorcaTemplates(
+    projectRoot,
+    ['export', '--to', 'gist', '--templates', id],
+    { timeout: 30000 },
+  );
+  // The CLI prints the gist URL (from `gh gist create`) as its final stdout line.
+  const match = stdout.match(/https?:\/\/\S+/);
+  return match ? match[0] : null;
+}
+
+function handleZipImport(req, res) {
+  const dstTier = req.query.dst_tier;
+  if (!isValidTier(dstTier)) {
+    return res.status(400).json({
+      ok: false,
+      error: `dst_tier must be one of: ${TIERS.join(', ')}`,
+    });
+  }
+  if (rejectBuiltinWrite(res, dstTier, 'import to')) return;
+
+  const zipBuffer = req.body;
+  const tmpPath = join(
+    tmpdir(),
+    `worca-import-${Math.random().toString(36).slice(2)}.zip`,
+  );
+  try {
+    writeFileSync(tmpPath, zipBuffer);
+    const stdout = runWorcaTemplates(
+      req.project.projectRoot,
+      ['import', '--from', tmpPath, '--scope', dstTier, '--non-interactive'],
+      { timeout: 60000 },
+    );
+    // Best-effort summary: the CLI may print imported template ids to stdout
+    const imported = [];
+    for (const line of (stdout || '').split('\n')) {
+      const m = line.match(/imported[:\s]+([a-z0-9_-]+)/i);
+      if (m) imported.push({ id: m[1], tier: dstTier });
+    }
+    res.json({ ok: true, count: imported.length || 1, imported });
+  } catch (err) {
+    res
+      .status(statusForCliCode(err.cliCode))
+      .json({ ok: false, error: err.message, code: err.cliCode });
+  } finally {
+    try {
+      rmSync(tmpPath, { force: true });
+    } catch {
+      /* ignore cleanup errors */
+    }
+  }
+}
+
+function handleJsonImport(req, res) {
+  const { bundle, dst_tier: dstTier } = req.body || {};
+  if (!bundle || typeof bundle !== 'object') {
+    return res
+      .status(400)
+      .json({ ok: false, error: 'bundle must be a JSON object' });
+  }
+  if (!isValidTier(dstTier)) {
+    return res.status(400).json({
+      ok: false,
+      error: `dst_tier must be one of: ${TIERS.join(', ')}`,
+    });
+  }
+  if (rejectBuiltinWrite(res, dstTier, 'import to')) return;
+  try {
+    const result = importBundle(req.project.projectRoot, bundle, dstTier);
+    res.json({ ok: true, ...result });
+  } catch (err) {
+    res
+      .status(statusForCliCode(err.cliCode))
+      .json({ ok: false, error: err.message, code: err.cliCode });
+  }
+}
+
 function importBundle(projectRoot, bundle, tier) {
   if (!bundle || !Array.isArray(bundle.templates)) {
     throw new Error('Bundle must contain a "templates" array');
@@ -434,31 +561,21 @@ export function createTemplatesRoutes() {
    * doesn't match the literal "import" path segment as a tier
    * parameter (which would 400 with "tier must be one of …").
    *
-   * Body: { bundle: {templates: [...]}, dst_tier }
+   * Accepts two content types:
+   *   application/zip  — raw zip bytes; dst_tier as query param
+   *   application/json — { bundle: {templates: [...]}, dst_tier }
    */
-  router.post('/templates/import', (req, res) => {
-    const { bundle, dst_tier: dstTier } = req.body || {};
-    if (!bundle || typeof bundle !== 'object') {
-      return res
-        .status(400)
-        .json({ ok: false, error: 'bundle must be a JSON object' });
-    }
-    if (!isValidTier(dstTier)) {
-      return res.status(400).json({
-        ok: false,
-        error: `dst_tier must be one of: ${TIERS.join(', ')}`,
-      });
-    }
-    if (rejectBuiltinWrite(res, dstTier, 'import to')) return;
-    try {
-      const result = importBundle(req.project.projectRoot, bundle, dstTier);
-      res.json({ ok: true, ...result });
-    } catch (err) {
-      res
-        .status(statusForCliCode(err.cliCode))
-        .json({ ok: false, error: err.message, code: err.cliCode });
-    }
-  });
+  router.post(
+    '/templates/import',
+    expressRaw({ type: 'application/zip', limit: '1mb' }),
+    (req, res) => {
+      const ctype = req.headers['content-type'] || '';
+      if (ctype.startsWith('application/zip')) {
+        return handleZipImport(req, res);
+      }
+      return handleJsonImport(req, res);
+    },
+  );
 
   /**
    * POST /api/projects/:projectId/templates/validate
@@ -611,9 +728,11 @@ export function createTemplatesRoutes() {
    * POST /api/projects/:projectId/templates/:tier/:id/rename
    * Body: { dst_tier, dst_id }
    *
-   * Same best-effort composition as before — duplicate then delete.
-   * partial_rename (500) when the second leg fails after the first
-   * lands on disk.
+   * Delegates to `worca templates rename` — a single CLI call that runs
+   * duplicate → pointer-rewrite → delete atomically in one process.
+   * partial_rename (500) is surfaced when the CLI reports that duplicate
+   * succeeded but delete failed (exit code 3, stderr contains
+   * "partial_rename").
    */
   router.post('/templates/:tier/:id/rename', (req, res) => {
     const { tier: srcTier, id: srcId } = req.params;
@@ -646,25 +765,33 @@ export function createTemplatesRoutes() {
     }
 
     try {
-      duplicateTemplateViaCli(projectRoot, srcId, dstId, dstTier);
+      runWorcaTemplates(projectRoot, [
+        'rename',
+        '--src-id',
+        srcId,
+        '--src-scope',
+        srcTier,
+        '--dst-id',
+        dstId,
+        '--dst-scope',
+        dstTier,
+      ]);
     } catch (err) {
+      if (err.cliCode === 'partial_rename') {
+        return res.status(500).json({
+          ok: false,
+          code: 'partial_rename',
+          error: `Renamed to "${dstId}" (${dstTier}) but failed to remove the source "${srcId}" (${srcTier}): ${err.message}`,
+          src_tier: srcTier,
+          src_id: srcId,
+          dst_tier: dstTier,
+          dst_id: dstId,
+        });
+      }
       return res
         .status(statusForCliCode(err.cliCode))
         .json({ ok: false, error: err.message, code: err.cliCode });
     }
-    try {
-      deleteTemplateViaCli(projectRoot, srcTier, srcId);
-    } catch (err) {
-      return res.status(500).json({
-        ok: false,
-        code: 'partial_rename',
-        error: `Renamed to "${dstId}" (${dstTier}) but failed to remove the source "${srcId}" (${srcTier}): ${err.message}`,
-        src_tier: srcTier,
-        src_id: srcId,
-        dst_tier: dstTier,
-        dst_id: dstId,
-      });
-    }
     res.json({
       ok: true,
       src_tier: srcTier,
@@ -676,13 +803,27 @@ export function createTemplatesRoutes() {
 
   /**
    * GET /api/projects/:projectId/templates/:tier/:id/bundle
+   *
+   * Optional ?mode=standalone|delta (default standalone). Standalone emits a
+   * self-contained bundle (config materialised + prompts resolved); delta emits
+   * the sparse overlay. Output format (zip vs JSON) is auto-detected.
    */
   router.get('/templates/:tier/:id/bundle', (req, res) => {
     const { tier, id } = req.params;
     if (rejectInvalidTierId(res, tier, id)) return;
+    const mode = req.query.mode === 'delta' ? 'delta' : 'standalone';
     try {
-      const bundle = exportBundle(req.project.projectRoot, id);
-      res.json({ ok: true, bundle });
+      const result = exportBundle(req.project.projectRoot, id, mode);
+      if (!result.json) {
+        res.setHeader('Content-Type', 'application/zip');
+        res.setHeader(
+          'Content-Disposition',
+          `attachment; filename="${result.filename}"`,
+        );
+        res.send(result.data);
+      } else {
+        res.json({ ok: true, bundle: result.data });
+      }
     } catch (err) {
       res
         .status(statusForCliCode(err.cliCode))
@@ -690,6 +831,103 @@ export function createTemplatesRoutes() {
     }
   });
 
+  /**
+   * POST /api/projects/:projectId/templates/:tier/:id/bundle?format=gist
+   *
+   * Create a (secret) GitHub gist from the template bundle and return its URL.
+   * Gist creation is a mutation (it shells out to `gh gist create`), so it is a
+   * POST distinct from the GET bundle download above. Only `?format=gist` is
+   * accepted here; zip/JSON downloads use the GET route. The client copies the
+   * returned `gist_url` to the clipboard so the template can be shared and
+   * imported elsewhere via `worca templates import --from <url>`.
+   */
+  router.post('/templates/:tier/:id/bundle', (req, res) => {
+    const { tier, id } = req.params;
+    if (rejectInvalidTierId(res, tier, id)) return;
+    if (req.query.format !== 'gist') {
+      return res.status(400).json({
+        ok: false,
+        error: 'unsupported bundle POST format — use ?format=gist',
+      });
+    }
+    try {
+      const gistUrl = exportGist(req.project.projectRoot, id);
+      if (!gistUrl) {
+        return res.status(502).json({
+          ok: false,
+          error: 'gist created but no URL was returned by gh',
+        });
+      }
+      res.json({ ok: true, gist_url: gistUrl });
+    } catch (err) {
+      // gh-missing / gist-create failures arrive here with the CLI stderr as the
+      // message (it mentions "gh"/"gist", which the client maps to a friendly
+      // "GitHub CLI is not available" toast).
+      res
+        .status(statusForCliCode(err.cliCode))
+        .json({ ok: false, error: err.message, code: err.cliCode });
+    }
+  });
+
+  /**
+   * GET /api/projects/:projectId/templates/:tier/:id/overlays
+   *
+   * Returns every overlay .md file from <tmpl>/agents/, keyed by filename.
+   */
+  router.get('/templates/:tier/:id/overlays', (req, res) => {
+    const { tier, id } = req.params;
+    if (rejectInvalidTierId(res, tier, id)) return;
+    const { projectRoot } = req.project;
+    const tierDir = dirForTier(projectRoot, tier);
+    const tmplDir = join(tierDir, id);
+    if (!existsSync(join(tmplDir, 'template.json'))) {
+      return res.status(404).json({
+        ok: false,
+        error: `Template "${id}" not found in ${tier} scope`,
+      });
+    }
+    try {
+      const agentsDir = join(tmplDir, 'agents');
+      const overlays = {};
+      if (existsSync(agentsDir)) {
+        for (const f of readdirSync(agentsDir)) {
+          if (!_OVERLAY_NAME_RE.test(f)) continue;
+          try {
+            overlays[f] = readFileSync(join(agentsDir, f), 'utf8');
+          } catch {
+            /* skip unreadable files */
+          }
+        }
+      }
+      res.json({ ok: true, overlays });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: err.message });
+    }
+  });
+
+  /**
+   * GET /api/projects/:projectId/templates/:tier/:id/prompts
+   *
+   * Effective per-stage prompt model for the editor's "Prompts" tab: each agent
+   * `*.md` and user-prompt `*.block.md` resolved against the built-in core
+   * prompts, classified as 'builtin' (fallback), 'pipeline' (replace), or
+   * 'extends' (append/overwrite merge). Unlike /overlays this is never empty —
+   * a template with no overlays still shows every built-in prompt. Tolerant of a
+   * missing template dir (returns core-only) so the tab works for new drafts.
+   */
+  router.get('/templates/:tier/:id/prompts', (req, res) => {
+    const { tier, id } = req.params;
+    if (rejectInvalidTierId(res, tier, id)) return;
+    const { projectRoot } = req.project;
+    const coreDir = join(projectRoot, '.claude', 'worca', 'agents', 'core');
+    const overlayDir = join(dirForTier(projectRoot, tier), id, 'agents');
+    try {
+      res.json({ ok: true, prompts: buildPromptsModel(coreDir, overlayDir) });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: err.message });
+    }
+  });
+
   /**
    * PUT /api/projects/:projectId/default-template
    *