@worca/app 1.2.0-rc.2 → 1.2.0

package/ui/server.mjs

@@ -42,7 +42,10 @@ import {
   askMaxTurns, askMaxBudgetUsd, setAskMaxTurns, setAskMaxBudgetUsd, assertAskLimitInputs,
   chatPrefs, setChatPrefs,
   debugSpawnEnabled as storedDebugSpawnEnabled, effectiveDebugSpawn, setDebugSpawnEnabled, assertDebugSpawnInput, SETTINGS_POST_KEYS,
+  titleModel as storedTitleModel, setTitleModel, assertTitleModelInput,
+  hideBuiltinModels, setHideBuiltinModels, assertHideBuiltinModelsInput,
 } from '../src/core/settings.mjs';
+import { describeTitleModel } from '../src/core/title.mjs';
 import {
   ASK_ID_RE, createThread as askCreateThread, getThread as askGetThread,
   listThreads as askListThreads, updateThread as askUpdateThread,
@@ -85,7 +88,7 @@ import { pickFolderNative } from '../src/core/folder-dialog.mjs';
 import { listFolders } from '../src/core/fs-browse.mjs';
 import {
   readConfig, setStep, addCustomModel, removeCustomModel, listModels,
-  PREDEFINED_MODELS, agentSteps, EFFORTS,
+  PREDEFINED_MODELS, agentSteps, EFFORTS, catalogHasModel,
   readRunConfig, setNodeModel, setFeedbackCycles, setWireCycles, setActiveWorkflow, resetWorkflowConfig,
   globalModelRefs, removeGlobalModelAndRefs, promoteCustomModel, costUnreliableModelIds,
 } from '../src/core/config.mjs';
@@ -107,7 +110,10 @@ import {
 } from '../src/core/workflows.mjs';
 import { registryPortsFn } from '../src/core/graph/registry-ports.mjs';
 import { sweepV1Runs, V1_RUN_RETIRED } from '../src/core/db.mjs';
-import { validateGraph, AGENT_TUNABLES } from '../src/shared/graph/validate.mjs';
+import { exportWorkflow, exportWorkflowPlugin, ON_CONFLICT_MODES, RESOLUTION_CHOICES } from '../src/core/workflow-export.mjs';
+import {
+  saveGraphWorkflow, importGraphWorkflow, exportGraphJson, workflowFileSlug, nodeDefaultsError,
+} from '../src/core/workflow-share.mjs';
 import { loadAgentRegistry } from '../src/core/agent-registry.mjs';
 import {
   listLocalBranches, currentBranch, isValidSourceRef, sweepRunRoots, sweepLegacyWorktreesAll,
@@ -126,7 +132,7 @@ import { createAgentGen } from '../src/core/agent-gen.mjs';
 import { listAgents, readAgent, createAgent, updateAgent, deleteAgent, AGENT_KEY_RE } from '../src/core/agent-store.mjs';
 import {
   listInstalledPlugins, installPlugin, updatePlugin, uninstallPlugin,
-  setPluginEnabled, doctorPlugin,
+  setPluginEnabled, doctorPlugin, linkPlugin,
   listOrphanPluginData, purgePluginData,
 } from '../src/core/plugin-store.mjs';
 import { fetchCandidate } from '../src/core/plugin-repo.mjs';
@@ -149,7 +155,7 @@ import { createNotifier } from '../src/core/chat/notifier.mjs';
 import { TokenBucket } from '../src/core/chat/rate-limiter.mjs';
 import { renderTest } from '../src/core/chat/renderers.mjs';
 import { readPluginsLock, pluginCurrentDir } from '../src/core/plugins-lock.mjs';
-import { normalizeManifest, PLUGIN_NAME_RE as MANIFEST_PLUGIN_NAME_RE } from '../src/core/plugin-manifest.mjs';
+import { normalizeManifest, validatePluginDir, PLUGIN_NAME_RE as MANIFEST_PLUGIN_NAME_RE } from '../src/core/plugin-manifest.mjs';
 import { listTaskSources, retryWriteback } from '../src/core/sources.mjs';
 import { callSource, PluginOpError } from '../src/core/plugin-shim.mjs';
 import { HLJS_GRAMMAR_IDS } from './public/hljs-loader.mjs';
@@ -177,7 +183,24 @@ const PUBLIC_DIR = path.join(__dirname, 'public');
 const AGENTS_DIR = path.join(PROJECT_ROOT, 'agents');
 const SKILLS_DIR = path.join(PROJECT_ROOT, 'skills');
 const require = createRequire(import.meta.url);
-const PKG_VERSION = require('../package.json').version;
+const PKG = require('../package.json');
+const PKG_VERSION = PKG.version;
+// Settings ▸ About identity, fixed at module load. repository.url is normalised
+// from npm's git forms (git+https, ssh://git@, git://, scp-style git@host:path)
+// to a browsable https URL; releaseUrl points at the tag the release workflow
+// publishes from (.github/workflows/release-npm-app.yml: worca-app-v<version>).
+const repoWebUrl = (raw) => String(raw || '')
+  .replace(/^git\+/, '')
+  .replace(/^ssh:\/\/git@/, 'https://')
+  .replace(/^git:\/\//, 'https://')
+  .replace(/^git@([^:/]+):/, 'https://$1/')
+  .replace(/\.git$/, '');
+const APP_REPO_URL = repoWebUrl(PKG.repository && PKG.repository.url);
+const APP_INFO = Object.freeze({
+  version: PKG_VERSION || '',
+  repoUrl: APP_REPO_URL,
+  releaseUrl: APP_REPO_URL && PKG_VERSION ? `${APP_REPO_URL}/releases/tag/worca-app-v${PKG_VERSION}` : '',
+});
 const HLJS_LANGUAGE_FILE_RE = /^[a-z0-9][a-z0-9-]{0,63}\.min\.js$/;
 // Primaries plus the sub-language grammars their instances register
 // (hljs-loader.mjs); a shipped but unmapped grammar stays a plain 404.
@@ -2478,9 +2501,11 @@ app.delete('/api/projects', async (req, res) => {
 // user's machine); when it reports `unsupported` the UI falls back to an
 // in-app modal fed by GET /api/fs/dirs. Localhost-only like every route here
 // (global isLocalRequest middleware).
-app.post('/api/fs/pick-folder', async (_req, res) => {
+app.post('/api/fs/pick-folder', async (req, res) => {
   try {
-    res.json(await pickFolderNative());
+    // `purpose` only picks the dialog title from a closed set (folder-dialog.mjs).
+    const purpose = typeof req.body?.purpose === 'string' ? req.body.purpose : undefined;
+    res.json(await pickFolderNative({ purpose }));
   } catch (err) {
     res.status(500).json({ error: err && err.message ? err.message : String(err) });
   }
@@ -2769,6 +2794,10 @@ app.get('/api/workspaces/:id/runs/:runId/artifact', async (req, res) => {
 //   projectsRootDefault : what applies when projectsRoot is blank — the env tier
 //                         when exported, else defaultRoot(). The UI placeholder.
 //                         Additive; `default` keeps its `root` meaning.
+//   app                 : { version, repoUrl, releaseUrl } — static identity for
+//                         the About card (APP_INFO, from package.json). GET-only:
+//                         it is not a setting, so POST keeps echoing
+//                         settingsState() + chat unchanged.
 // POST /api/settings -> set either key and return the resulting full state.
 //   Only keys PRESENT in the body are written, so a projectsRoot-only POST can
 //   never reset `root` (and vice versa). An explicitly empty value still resets
@@ -2788,6 +2817,9 @@ const settingsState = () => ({
   askMaxBudgetUsd: askMaxBudgetUsd(),
   debugSpawnEnabled: storedDebugSpawnEnabled(),          // what is STORED (the checkbox)
   debugSpawnEffective: effectiveDebugSpawn(),             // what the next spawn will DO, and why
+  titleModel: storedTitleModel(),                         // the STORED id (the select), null = run's model
+  titleModelEffective: describeTitleModel(),              // env override / stale id, for the hint line (#422)
+  hideBuiltinModels: hideBuiltinModels(),
 });
 
 // ---------------------------------------------------------------------------
@@ -2834,7 +2866,7 @@ app.post('/api/shutdown', (req, res) => {
 });
 
 app.get('/api/settings', (_req, res) => {
-  res.json({ ...settingsState(), chat: chatPrefs() });
+  res.json({ ...settingsState(), chat: chatPrefs(), app: APP_INFO });
 });
 
 app.get('/api/budget', (_req, res) => {
@@ -2847,6 +2879,12 @@ app.post('/api/settings', async (req, res) => {
   const hasBudgetKey = has('pipelineCostLimitUsd') || has('totalCostLimitUsd') || has('costLimitResetPeriod');
   const hasAskKey = has('askMaxTurns') || has('askMaxBudgetUsd');
   const hasDebugSpawnKey = has('debugSpawnEnabled');
+  const hasTitleModelKey = has('titleModel');
+  const hasHideBuiltinKey = has('hideBuiltinModels');
+  // #422: the title model is a SELECT over the catalog, so an id that is not a
+  // catalog member is a client bug (or a stale option) — refuse it here rather
+  // than store an id resolveModelEnv could never route.
+  const titleModelInput = hasTitleModelKey ? (body.titleModel ?? '') : undefined;
   // Normalize the budget keys first, then validate them as a SET before ANY write.
   // Each setter persists on its own, so a two-key POST whose second key is invalid
   // used to answer 400 with the first key already on disk, no budget-changed
@@ -2868,6 +2906,13 @@ app.post('/api/settings', async (req, res) => {
     assertCostLimitInputs(budget);
     assertAskLimitInputs(ask);
     if (hasDebugSpawnKey) assertDebugSpawnInput(body.debugSpawnEnabled);
+    if (hasTitleModelKey) {
+      assertTitleModelInput(titleModelInput);
+      if (titleModelInput !== '' && titleModelInput !== null && !catalogHasModel(titleModelInput)) {
+        throw new Error(`unknown model ${JSON.stringify(String(titleModelInput))} — pick one from the catalog`);
+      }
+    }
+    if (hasHideBuiltinKey) assertHideBuiltinModelsInput(body.hideBuiltinModels);
     // Root first: it is the one key whose setter can still fail AFTER the asserts
     // above (an unusable path), so every other key's write must come after it or
     // a mixed POST would answer 400 with those keys already applied on disk.
@@ -2886,10 +2931,12 @@ app.post('/api/settings', async (req, res) => {
     if (has('askMaxTurns')) await setAskMaxTurns(ask.askMaxTurns);
     if (has('askMaxBudgetUsd')) await setAskMaxBudgetUsd(ask.askMaxBudgetUsd);
     if (hasDebugSpawnKey) await setDebugSpawnEnabled(body.debugSpawnEnabled);
+    if (hasTitleModelKey) await setTitleModel(titleModelInput);
+    if (hasHideBuiltinKey) await setHideBuiltinModels(body.hideBuiltinModels);
     if (hasBudgetKey) emitChanged('budget-changed');
     // Other open tabs repaint their Settings cards (a stale tab could otherwise
     // "save" its old checkbox state over this one with no feedback to either).
-    if (hasAskKey || hasDebugSpawnKey) emitChanged('settings-changed');
+    if (hasAskKey || hasDebugSpawnKey || hasTitleModelKey || hasHideBuiltinKey) emitChanged('settings-changed');
     res.json({ ...settingsState(), chat: chatPrefs() });
   } catch (err) {
     // The setters throw only on an unusable path -> client error (400).
@@ -3110,7 +3157,10 @@ const pluginModelsPayload = () => {
 };
 
 app.get('/api/models', (req, res) => {
-  res.json({ models: maskedGlobalModels(), plugin: pluginModelsPayload(), predefined: PREDEFINED_MODELS, efforts: EFFORTS });
+  res.json({
+    models: maskedGlobalModels(), plugin: pluginModelsPayload(), predefined: PREDEFINED_MODELS, efforts: EFFORTS,
+    hideBuiltinModels: hideBuiltinModels(),   // the Models-view checkbox (#422)
+  });
 });
 
 app.post('/api/models', async (req, res) => {
@@ -3323,7 +3373,10 @@ app.post('/api/models/:id/test', async (req, res) => {
   const lc = id.toLowerCase();
   const global = listGlobalModels().find((m) => m.id.toLowerCase() === lc);
   const plugin = global ? null : listPluginModels().find((m) => m.id.toLowerCase() === lc);
-  if (!global && !plugin) return res.status(404).json({ error: `unknown model id ${JSON.stringify(id)}` });
+  // A built-in is testable too (#422): the Title-generation card offers it, and
+  // a first-party id with no routing env is exactly the spawn a run would make.
+  const builtin = !global && !plugin && PREDEFINED_MODELS.some((m) => m.id.toLowerCase() === lc);
+  if (!global && !plugin && !builtin) return res.status(404).json({ error: `unknown model id ${JSON.stringify(id)}` });
   if (plugin && plugin.secrets.length) {
     // Don't burn a spawn guaranteed to fail — resolveModelEnv drops unset secrets.
     const unset = pluginModelSecretStatus(plugin.plugin)
@@ -3347,25 +3400,35 @@ app.post('/api/models/:id/test', async (req, res) => {
 // /api/projects + /api/config delegation pattern: thin handlers, validation and
 // atomic persistence owned by src/core/workflows.mjs + workflow-validator.mjs.
 // ---------------------------------------------------------------------------
-// Validate one node-defaults block against the project-less catalog. Returns an
-// error message, or '' when the block is acceptable. Mirrors setStep's rules so a
-// workflow default can never name something a per-project override could not.
-function nodeDefaultsError(raw, models, where) {
-  if (raw == null) return '';
-  if (typeof raw !== 'object' || Array.isArray(raw)) return `defaults for ${where} must be an object`;
-  const model = typeof raw.model === 'string' ? raw.model.trim() : '';
-  const effort = typeof raw.effort === 'string' ? raw.effort.trim() : '';
-  const entry = model ? models.find((m) => m.id === model) : null;
-  if (model && !entry) return `unknown model "${model}"`;
-  // subagentModel is a fixed alias enum, NOT a catalog id: validated via the
-  // shared helper so a typo is a 400 with the same message every writer uses.
-  const subIssue = subagentModelIssue(raw.subagentModel);
-  if (subIssue) return subIssue;
-  if (!effort) return '';
-  if (!EFFORTS.includes(effort)) return `unknown effort "${effort}"`;
-  if (!entry) return 'select a model before choosing an effort';
-  if (!entry.efforts.includes(effort)) return `model "${model}" does not support effort "${effort}"`;
-  return '';
+// nodeDefaultsError (one node-defaults block vs the project-less catalog) lives
+// in src/core/workflow-share.mjs now, so `worca workflow import` applies the
+// same gate as the routes below.
+
+/** Error -> HTTP for the shared save/import/JSON path (workflow-share.mjs codes). */
+function sendWorkflowShareError(res, err) {
+  const code = err && err.code;
+  const message = err && err.message ? err.message : String(err);
+  if (code === 'BAD_REQUEST' || code === 'UNSUPPORTED') return badRequest(res, message);
+  // The 422 body is the SHARED validator's issue list, by construction: the
+  // composer renders exactly what it would have computed locally, so the server
+  // and the client can never disagree about why a graph is illegal. `summary`
+  // is the one-line V4 fold for surfaces with no issue list (the Import button).
+  if (code === 'INVALID_GRAPH') {
+    return res.status(422).json({
+      error: message, errors: err.errors || [], warnings: err.warnings || [],
+      ...(err.summary ? { summary: err.summary } : {}),
+    });
+  }
+  // C-3: a name that slugs onto the reserved wf_default is a caller error, not
+  // a server fault — 422, the same code the validator's refusal uses. MAJ-5: a
+  // minted id already in use is a 409 carrying that id, so the dialog can offer
+  // rename/overwrite. Both bodies carry NO issues/errors array on purpose:
+  // app.js's saveWorkflow maps `error` straight into the save dialog's message
+  // line, verbatim.
+  if (code === 'RESERVED_NAME') return res.status(422).json({ error: message });
+  if (code === 'ID_TAKEN') return res.status(409).json({ error: message, id: err.id });
+  if (code === 'NOT_FOUND') return res.status(404).json({ error: message });
+  return res.status(500).json({ error: message });
 }
 
 app.get('/api/workflows', async (req, res) => {
@@ -3394,63 +3457,61 @@ app.get('/api/workflows/:id', async (req, res) => {
     if (err && (err.code === 'NOT_FOUND' || err.code === 'ARCHIVED')) {
       return res.status(404).json({ error: err.message });
     }
+    // The row exists but its plugin is disabled: a conflict with the plugin's
+    // state, not a missing row — the message names the fix.
+    if (err && err.code === 'PLUGIN_DISABLED') return res.status(409).json({ error: err.message });
     res.status(500).json({ error: err && err.message ? err.message : String(err) });
   }
 });
 
 app.post('/api/workflows', async (req, res) => {
-  const body = req.body || {};
   // The v1 pipeline format is RETIRED: only graphs are accepted (spec §10.2).
   // The whole v1 arm (its steps-borne node defaults, validateWorkflow and
   // writeWorkflow) died with it — nothing reaches the v1 store through the API.
-  if (body.version !== 2) {
-    return badRequest(res, 'v1 pipeline templates are no longer accepted — save a graph (version 2)');
-  }
   // ── v2 graph save ──────────────────────────────────────────────────────────
-  // The 422 body is the SHARED validator's issue list, by construction: the
-  // composer renders exactly what it would have computed locally, so the server
-  // and the client can never disagree about why a graph is illegal.
-  const graph = {
-    id: typeof body.id === 'string' ? body.id : undefined,
-    name: typeof body.name === 'string' ? body.name.trim() : '',
-    domain: typeof body.domain === 'string' ? body.domain : undefined,
-    nodes: Array.isArray(body.nodes) ? body.nodes : [],
-    wires: Array.isArray(body.wires) ? body.wires : [],
-    ...(body.canvas && typeof body.canvas === 'object' ? { canvas: body.canvas } : {}),
-  };
-  if (!graph.name) return badRequest(res, 'name is required');
-  try {
-    // Catalog validation FIRST: a v2 node's `config` IS its defaults block (§4),
-    // so a value the per-project override could not name must not ride in
-    // through a template save. nodeDefaultsError checks the tunables (model +
-    // effort against the catalog, subagentModel against the alias enum), so
-    // only AGENT_TUNABLES are handed to it — topology keys (awaitAll, arity,
-    // planStoreSeed) never are.
-    const models = await listModels('');
-    for (const n of graph.nodes) {
-      if (!n || n.kind !== 'agent' || !n.config || typeof n.config !== 'object') continue;
-      const picked = Object.fromEntries(
-        AGENT_TUNABLES.filter((k) => k in n.config).map((k) => [k, n.config[k]]));
-      const bad = nodeDefaultsError(picked, models, `node "${n.id}"`);
-      if (bad) return badRequest(res, bad);
-    }
-    const portsFn = registryPortsFn(loadAgentRegistry(AGENTS_DIR));
-    const { errors, warnings } = validateGraph({ ...graph, version: 2 }, portsFn);
-    if (errors.length) return res.status(422).json({ error: 'invalid graph', errors, warnings });
-    // rejectCollision (MAJ-5): the body carried no id, so wf_<slug(name)> is a
-    // GUESS — it must never silently replace a pipeline the user can see.
-    const workflow = await writeGraphWorkflow(graph, { rejectCollision: true });
+  // Catalog check + shared validator + rejectCollision persistence live in
+  // workflow-share.mjs (saveGraphWorkflow): the SAME path the JSON import
+  // route and `worca workflow import` take, so they can never drift. A body
+  // WITHOUT an id mints wf_<slug(name)> — a GUESS that must never silently
+  // replace a pipeline the user can see (MAJ-5 -> 409).
+  try {
+    const { workflow, warnings } = await saveGraphWorkflow(req.body || {}, { agentsDir: AGENTS_DIR });
     return res.status(201).json({ workflow, warnings });
   } catch (err) {
-    // C-3: a name that slugs onto the reserved wf_default is a caller error, not
-    // a server fault — 422, the same code the validator's refusal uses. MAJ-5: a
-    // minted id already in use is a 409 carrying that id, so the dialog can offer
-    // rename/overwrite. Both bodies carry NO issues/errors array on purpose:
-    // app.js's saveWorkflow maps `error` straight into the save dialog's message
-    // line, verbatim.
-    if (err && err.code === 'RESERVED_NAME') return res.status(422).json({ error: err.message });
-    if (err && err.code === 'ID_TAKEN') return res.status(409).json({ error: err.message, id: err.id });
-    return res.status(500).json({ error: err && err.message ? err.message : String(err) });
+    return sendWorkflowShareError(res, err);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Share a workflow as JSON (issue #421). GET .../json is the unstamped v2 graph
+// of the STORED row (no id/origin/timestamps; `canvas` kept), served as a
+// download; POST /import-json feeds one back through the shared validator,
+// minting an id and suffixing the name (`Name (2)`) on a collision — never
+// overwrite. Registered BEFORE the /:id routes so the segment can never be read
+// as an id. (Not `/import`: test/shared-graph-purity.test.mjs scans ui/public
+// for `import '<spec>'` and a bare `import'` in app.js's fetch URL trips it.)
+// ---------------------------------------------------------------------------
+app.post('/api/workflows/import-json', async (req, res) => {
+  const body = req.body || {};
+  const src = body.workflow && typeof body.workflow === 'object' && !Array.isArray(body.workflow) ? body.workflow : null;
+  if (!src) return badRequest(res, 'workflow (the exported JSON object) is required');
+  try {
+    const r = await importGraphWorkflow(src, {
+      name: typeof body.name === 'string' ? body.name : undefined, agentsDir: AGENTS_DIR,
+    });
+    return res.status(201).json(r);
+  } catch (err) {
+    return sendWorkflowShareError(res, err);
+  }
+});
+
+app.get('/api/workflows/:id/json', async (req, res) => {
+  try {
+    const payload = await exportGraphJson(req.params.id);
+    res.setHeader('Content-Disposition', `attachment; filename="${workflowFileSlug(req.params.id)}.json"`);
+    res.type('application/json').send(JSON.stringify(payload, null, 2) + '\n');
+  } catch (err) {
+    sendWorkflowShareError(res, err);
   }
 });
 
@@ -3498,6 +3559,72 @@ app.delete('/api/workflows/:id', async (req, res) => {
   }
 });
 
+function workflowExportErrorStatus(code) {
+  if (code === 'NOT_FOUND') return 404;
+  if (code === 'BAD_REQUEST' || code === 'UNSUPPORTED' || code === 'MISSING_SKILL') return 400;
+  if (code === 'INVALID_GRAPH') return 422;
+  if (code === 'CONFLICT' || code === 'CANCELLED') return 409;
+  return 500;
+}
+
+app.post('/api/workflows/:id/export', async (req, res) => {
+  const body = req.body || {};
+  const destination = body.destination;
+  if (destination !== 'global' && destination !== 'project' && destination !== 'plugin') {
+    return badRequest(res, "destination must be 'global', 'project' or 'plugin'");
+  }
+  // ── destination 'plugin' (#421): a plugin folder the recipient links/reimports.
+  //    Same Plan/Apply shape as the Claude Code export, so the modal renders both.
+  if (destination === 'plugin') {
+    const pluginDir = resolveProjectDir(body.pluginDir);
+    if (!pluginDir) return badRequest(res, 'pluginDir is required for a plugin export');
+    try {
+      const result = await exportWorkflowPlugin({
+        workflowId: req.params.id, targetDir: pluginDir,
+        pluginName: typeof body.pluginName === 'string' ? body.pluginName : undefined,
+        keepVersion: !!body.keepVersion, dryRun: !!body.dryRun,
+      });
+      return res.json(result);
+    } catch (err) {
+      return res.status(workflowExportErrorStatus(err && err.code)).json({
+        error: err && err.message ? err.message : String(err),
+        ...(Array.isArray(err?.errors) ? { errors: err.errors } : {}),
+      });
+    }
+  }
+  let projectDir;
+  if (destination === 'project') {
+    projectDir = resolveProjectDir(body.projectDir);
+    if (!projectDir) return badRequest(res, 'projectDir is required for a project export');
+  }
+  // Validate conflict handling the same way the CLI does — the write loop only fails safe if
+  // it never sees a bogus value. An unrecognized onConflict/resolution is a caller error, not
+  // a silent overwrite.
+  if (body.onConflict !== undefined && !ON_CONFLICT_MODES.includes(body.onConflict)) {
+    return badRequest(res, `onConflict must be one of: ${ON_CONFLICT_MODES.join(', ')}`);
+  }
+  if (body.resolutions !== undefined) {
+    if (!body.resolutions || typeof body.resolutions !== 'object' || Array.isArray(body.resolutions)) {
+      return badRequest(res, 'resolutions must be an object keyed by path');
+    }
+    for (const [path, choice] of Object.entries(body.resolutions)) {
+      if (!RESOLUTION_CHOICES.includes(choice)) {
+        return badRequest(res, `invalid resolution ${JSON.stringify(choice)} for ${path} (allowed: ${RESOLUTION_CHOICES.join(', ')})`);
+      }
+    }
+  }
+  try {
+    const result = await exportWorkflow({
+      workflowId: req.params.id, destination, projectDir,
+      slug: body.slug, includeAgents: body.includeAgents !== false,
+      dryRun: !!body.dryRun, onConflict: body.onConflict, resolutions: body.resolutions,
+    });
+    res.json(result); // Plan {created,noop,updated,conflicts,warnings,orphans} OR Apply {written,skipped,...}
+  } catch (err) {
+    res.status(workflowExportErrorStatus(err && err.code)).json({ error: err && err.message ? err.message : String(err) });
+  }
+});
+
 // ---------------------------------------------------------------------------
 // Guardrail sets (global store, table guardrail_sets). The built-ins
 // Permissive / Normal / Strict are VIRTUAL (GUARDRAIL_PRESETS) — the server
@@ -4610,12 +4737,45 @@ app.get('/api/marketplaces', (req, res) => {
   } catch (err) { sendPluginError(res, err); }
 });
 
+// Dev-mode link of a LOCAL plugin folder — the `worca plugin link <dir>` path
+// (validate, symlink current/, import its workflow templates). Reached directly
+// via POST /api/plugins/link, and by POST /api/marketplaces when the "marketplace"
+// handed in turns out to be a single plugin folder (the natural thing to paste
+// after `Export… → Worca plugin`, issue #421).
+async function linkPluginDir(dir) {
+  const abs = resolveProjectDir(dir);
+  if (!abs) throw Object.assign(new Error('dir is required'), { code: 'BAD_REQUEST' });
+  const v = validatePluginDir(abs);
+  if (!v.ok || !v.manifest) {
+    const lines = v.problems.filter((p) => p.level === 'error').map((p) => p.message);
+    throw Object.assign(new Error(`cannot link ${abs}: ${lines.join('; ') || 'not a valid plugin folder'}`), { code: 'BAD_REQUEST' });
+  }
+  let out;
+  try { out = await linkPlugin(v.manifest.name, abs); }
+  catch (err) { throw Object.assign(err instanceof Error ? err : new Error(String(err)), { code: err?.code || 'BAD_REQUEST' }); }
+  reloadChatWorkers(v.manifest.name);
+  return out; // { ok, name, dir, workflows: { imported, skipped } }
+}
+
+app.post('/api/plugins/link', async (req, res) => {
+  try {
+    res.json(await linkPluginDir(req.body && typeof req.body.dir === 'string' ? req.body.dir : ''));
+  } catch (err) { sendPluginError(res, err); }
+});
+
 app.post('/api/marketplaces', async (req, res) => {
   const url = req.body && typeof req.body.url === 'string' ? req.body.url.trim() : '';
   if (!url) return badRequest(res, 'url is required');
   try {
     res.json({ ok: true, marketplace: withInstalled([await addMarketplace(url)])[0] });
-  } catch (err) { sendPluginError(res, err); }
+  } catch (err) {
+    if (err && err.code === 'PLUGIN_FOLDER') {
+      // Not a marketplace but a plugin folder: link it, and SAY that is what happened.
+      try { return res.json({ ok: true, linked: true, plugin: await linkPluginDir(err.dir) }); }
+      catch (e) { return sendPluginError(res, e); }
+    }
+    sendPluginError(res, err);
+  }
 });
 
 // refresh-all (a distinct path from :id/refresh, so registration order is irrelevant).