Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(ok): Wave 2 group 7 folder-config/template/seed/client-logs + spawn-cursor/handoff native (PRD-8400) (#3986)
omar-inkeepcadd209f760d
diff --git a/packages/app/tests/integration/template-handler-contract.test.ts b/packages/app/tests/integration/template-handler-contract.test.tsindex af1d336f7..4edfd9fdd 100644--- a/packages/app/tests/integration/template-handler-contract.test.ts+++ b/packages/app/tests/integration/template-handler-contract.test.ts@@ -2,8 +2,13 @@* Template-handler asymmetry contract — static analysis gate.** Mirror of `conflict-gate-coverage.test.ts` / `attribution-sweep-coverage.test.ts`:- * statically scans the four mutating template handlers in `api-extension.ts` and- * pins three deliberate asymmetries the templates-as-content cutover preserves.+ * statically scans the four mutating template handlers and pins three deliberate+ * asymmetries the templates-as-content cutover preserves. The handlers live in+ * whichever source currently owns them — `api-extension.ts`'s legacy dispatch or+ * a native `http/*-routes.ts` group factory — so the scan builds its source set+ * from the union of both (via `listNativeRouteFiles`), exactly as the sibling+ * meta-tests do, and a future lift between those files cannot silently vacate+ * this gate.* These are properties of the HANDLER source, not of the end-to-end runtime — the* `files` derived-view channel also fires from raw disk events, and the CRDT* write path's writeTracker suppresses its own self-writes, so the honest thing@@ -15,21 +20,33 @@import { readFileSync } from 'node:fs';import { join } from 'node:path';import { describe, expect, test } from 'vitest';+import {+ HANDLER_RUN_END_NEEDLES,+ listNativeRouteFiles,+} from '../native-route-files.test-helper.ts';-const API_EXT_PATH = join(import.meta.dirname, '../../../server/src/api-extension.ts');-const source = readFileSync(API_EXT_PATH, 'utf8');+const SERVER_SRC = join(import.meta.dirname, '../../../server/src');+const SOURCES = ['api-extension.ts', ...listNativeRouteFiles(SERVER_SRC)].map((rel) =>+ readFileSync(join(SERVER_SRC, rel), 'utf8'),+);/**- * Slice one `const handle... = withValidation(` template handler body out of the- * source, bounded at the next top-level handler / route table — the same- * extractor shape the sibling meta-tests use.+ * Slice one `const handle... = withValidation(` template handler body out of+ * whichever source owns it, bounded at the next top-level handler or the group's+ * route-record declaration — the same extractor shape the sibling meta-tests use.*/function extractHandlerBody(handlerName: string): string {+ const source = SOURCES.find((s) => s.includes(`const ${handlerName} = withValidation(`));+ if (!source) throw new Error(`${handlerName}: withValidation handler not found in source`);const start = source.indexOf(`const ${handlerName} = withValidation(`);- if (start === -1) throw new Error(`${handlerName}: withValidation handler not found in source`);- const nextConst = source.indexOf('\n const handle', start + 1);- const nextRoutes = source.indexOf('\n const routes:', start + 1);- const candidates = [nextConst, nextRoutes].filter((i) => i !== -1);+ const candidates = [+ '\n async function handle',+ '\n const handle',+ ...HANDLER_RUN_END_NEEDLES,+ '\n return {',+ ]+ .map((needle) => source.indexOf(needle, start + 1))+ .filter((i) => i !== -1);const next = candidates.length === 0 ? -1 : Math.min(...candidates);return source.slice(start, next === -1 ? source.length : next);}diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.tsindex e3f4ece88..829304bd7 100644--- a/packages/server/src/api-extension.ts+++ b/packages/server/src/api-extension.ts@@ -52,8 +52,6 @@ import {BranchInfoResponseSchema,CheckoutRequestSchema,CheckoutResponseSchema,- ClientLogsRequestSchema,- ClientLogsSuccessSchema,CONFIG_DOC_NAME_OKIGNORE,type ConfigDiagnosticsReport,CreateFolderRequestSchema,@@ -81,9 +79,6 @@ import {encodeShareUrl,estimateSkillCost,externalSkillLiveDocName,- FolderConfigGetSuccessSchema,- FolderConfigPutRequestSchema,- FolderConfigPutSuccessSchema,FrontmatterPatchRequestSchema,FrontmatterPatchSuccessSchema,FrontmatterSchemaWriteRequestSchema,@@ -135,7 +130,6 @@ import {type ProblemType,parseCanonicalGitHubShareUrl,parseFrontmatterRecord,- parseTemplateFile,prependFrontmatter,projectSkillContentDocName,RENAMED_PACK_SKILLS,@@ -146,12 +140,6 @@ import {readFmMap,SaveVersionRequestSchema,SaveVersionSuccessSchema,- SeedApplyRequestSchema,- SeedApplySuccessSchema,- SeedInstallPackSkillRequestSchema,- SeedInstallPackSkillSuccessSchema,- SeedListPacksSuccessSchema,- SeedPlanSuccessSchema,ShareConstructUrlRequestSchema,ShareConstructUrlResponseSchema,SharePublishNameCheckResponseSchema,@@ -216,26 +204,15 @@ import {skillLiveDocName,stripFrontmatter,summarizeLintPluginFailures,- TEMPLATE_NAME_REGEX,- TemplateDeleteSuccessSchema,- TemplateGetSuccessSchema,- TemplateImportRequestSchema,- TemplateImportSuccessSchema,- TemplateMoveRequestSchema,- TemplateMoveSuccessSchema,- TemplatePutRequestSchema,- TemplatePutSuccessSchema,TestFlushGitSuccessSchema,TestRescanBacklinksSuccessSchema,TestRescanFilesSuccessSchema,TestResetSuccessSchema,TrashCleanupRequestSchema,TrashCleanupSuccessSchema,- templateContentDocName,UploadAssetSuccessSchema,UploadRequestSchema,USER_SKILL_EDITOR_IDS,- unwrapFrontmatterFences,type ValidationDiagnostic,} from '@inkeep/open-knowledge-core';import {@@ -268,7 +245,6 @@ import {upsertLockEntry,type WellKnownIndex,} from '@inkeep/open-knowledge-core/skills-catalog';-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';import { type Entry, fromBuffer as yauzlFromBuffer, type ZipFile } from 'yauzl';import {type AcpHarnessAvailability,@@ -301,8 +277,6 @@ import { CommentThreadStore } from './comments/thread-store.ts';import { getLocalDir } from './config/paths.ts';import { CONFIG_VALIDATION_REVERT_ORIGIN } from './config-edit-origin.ts';import { DocInConflictError, isDocInConflict, respondDocInConflict } from './conflict-errors.ts';-import { enrichDirectory } from './content/enrichment.ts';-import { applyFolderFrontmatterPatch } from './content/folder-frontmatter-write.ts';import {applySkillBundleFileDelete,applySkillBundleFileRename,@@ -317,13 +291,6 @@ import {} from './content/skills-write.ts';import { applySubstitution, todayIsoUtc } from './content/substitution.ts';import { resolveTemplatesAvailable } from './content/templates-resolver.ts';-import {- applyTemplateDelete,- applyTemplateMove,- applyTemplateWrite,- composeTemplateContent,- type TemplateFrontmatter,-} from './content/templates-write.ts';import {evaluateContentDivergence,toContentDivergenceWarning,@@ -348,7 +315,6 @@ import {createOsProbe,type InstalledAgentScheme,} from './handoff-api.ts';-import { handleHandoffDispatch } from './handoff-dispatch-api.ts';import { findHubCandidates } from './hub-candidates.ts';import {readInstalledSkills,@@ -440,7 +406,6 @@ import {validateSkillForInstall,} from './skill-projection.ts';import { rewriteSkillRefsAcrossScope, type SkillRefRewrite } from './skill-ref-rename.ts';-import { handleSpawnCursor } from './spawn-cursor-api.ts';import { assertRealpathWithinDir } from './symlink-guard.ts';import { HashingPassThrough, mintTempUploadPath } from './upload-streaming.ts';@@ -531,7 +496,6 @@ import {tracedMkdirSync,tracedRenameSync,tracedRmSync,- tracedUnlinkSync,tracedWriteFileSync,} from './fs-traced.ts';import {@@ -553,6 +517,7 @@ import {errorResponse,type HttpErrorStatus,} from './http/error-response.ts';+import { createFolderTemplateRoutes } from './http/folder-template-routes.ts';import { errnoCode } from './http/handler-utils.ts';import { createHistoryRoutes } from './http/history-routes.ts';import { assertSingleRouterOwnership, type NativeApiHandle } from './http/http-app.ts';@@ -563,9 +528,11 @@ import { methodRouter } from './http/method-router.ts';import { createMetricsRoutes } from './http/metrics-routes.ts';import { getRequestId } from './http/request-id.ts';import { validateBody, withValidation } from './http/request-validation.ts';+import { createSeedRoutes } from './http/seed-routes.ts';import { createSkillsReadRoutes } from './http/skills-read-routes.ts';import { createSkillsShRoutes } from './http/skills-sh-routes.ts';import { successResponse } from './http/success-response.ts';+import { createSystemActionsRoutes } from './http/system-actions-routes.ts';import {createWorkspaceToolsRoutes,type GeneratedIndexSettingsStatus,@@ -634,16 +601,6 @@ import {type RenameLogEntry,resolveDocPathAtCommit,} from './rename-log.ts';-import {- applySeed,- coercePackId,- installPackSkillOnDemand,- listStarterPacks,- planSeed,- type ScaffoldPlan,- SeedPrerequisiteError,- SeedRootDirError,-} from './seed/index.ts';import type { PairedWriteOrigin } from './server-observers.ts';import { createAssetService } from './services/assets.ts';import { createFileOpsService } from './services/file-ops.ts';@@ -5102,8 +5059,9 @@ export function createApiExtension(/*** Contributor `docs` key for a non-doc `.ok/` artifact, so a folder-scoped- * timeline query resolves it. Mirrors `checkTemplateConflictGate`'s- * `<folder>/.ok/templates/<name>` shape; folder frontmatter keys to+ * timeline query resolves it. Mirrors `checkTemplateConflictGate`'s (now in+ * `http/folder-template-routes.ts`) `<folder>/.ok/templates/<name>` shape;+ * folder frontmatter keys to* `<folder>/.ok/frontmatter`; a folder itself keys to its own path.*/function okArtifactKey(@@ -11480,211 +11438,6 @@ export function createApiExtension(}}- // ─── `ok seed` scaffolder endpoints ──────────────────────────────────────- // GET /api/seed/plan → 200 {plan} (RFC 9457 problem+json on error)- // POST /api/seed/apply with { plan } → 200 {result} (RFC 9457 problem+json on error)- //- // Same `planSeed` / `applySeed` logic the CLI subcommand and Electron IPC- // handler use. The IPC bridge (`ok:seed:plan` / `ok:seed:apply`) keeps its- // in-process discriminated-union shape (`{ok: true, plan}` / `{ok: false,- // error: {kind, message}}`); the HTTP fallback in `seedClient()` translates- // RFC 9457 problem+json back to that shape at the renderer boundary so- // `SeedDialog` / `EmptyEditorState` are transport-agnostic.- // Gated on `checkLocalOpSecurity` because the operation mutates the local- // filesystem; same contract as /api/local-op/* and /api/installed-agents.-- /**- * GET `/api/seed/plan?rootDir=brain&packId=software-lifecycle` — preview the- * scaffold for a given subfolder + pack. `rootDir` defaults to `.` (project- * root). `packId` defaults to the registry default (`'knowledge-base'`) for- * back-compat with single-scaffold callers; unknown ids coerce to undefined- * and `resolvePack()` falls back to the default.- *- * Prerequisite-missing (no git init) → 422 with- * `urn:ok:error:seed-prerequisite-missing`; invalid-root (escape segments,- * absolute path) → 400 with `urn:ok:error:seed-invalid-root`. Both surface- * a `detail` carrying the underlying message so renderers can echo it.- */- async function handleSeedPlan(req: IncomingMessage, res: ServerResponse): Promise<void> {- if (!checkLocalOpSecurity(req, res, { handler: 'seed-plan' })) return;- if (req.method !== 'GET') {- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {- handler: 'seed-plan',- extraHeaders: { Allow: 'GET' },- });- return;- }- const url = new URL(req.url ?? '/', 'http://localhost');- const rootDir = url.searchParams.get('rootDir') ?? undefined;- const rawPackId = url.searchParams.get('packId');- const packId = coercePackId(rawPackId);- // Trust-boundary symmetry with the CLI: if the caller passed a `packId`- // but it doesn't name a registered pack, reject explicitly rather than- // silently fall back to the default pack (CLI returns "Unknown pack"- // failure on the same input).- if (rawPackId !== null && rawPackId !== '' && packId === undefined) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Unknown packId.', {- handler: 'seed-plan',- detail: `Pack id "${rawPackId}" is not registered.`,- });- return;- }- try {- const plan = await planSeed({ projectDir: contentDir, rootDir, packId });- successResponse(res, 200, SeedPlanSuccessSchema, { plan }, { handler: 'seed-plan' });- } catch (err) {- if (err instanceof SeedPrerequisiteError) {- errorResponse(- res,- 422,- 'urn:ok:error:seed-prerequisite-missing',- 'Seed prerequisite missing.',- { handler: 'seed-plan', cause: err },- );- return;- }- if (err instanceof SeedRootDirError) {- // Fixed-vocabulary safe `detail` per RFC 9457 §3.1.5 — gives the- // client an actionable message without leaking the rejected path- // (raw err message goes through `cause` → Pino, never on wire).- errorResponse(res, 400, 'urn:ok:error:seed-invalid-root', 'Invalid seed root directory.', {- handler: 'seed-plan',- detail: 'The provided root directory is not within the workspace content directory.',- cause: err,- });- return;- }- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'seed-plan',- cause: err,- });- }- }-- /**- * `POST /api/seed/apply` — apply a pre-computed ScaffoldPlan to disk.- * Body accepts `{plan, packId?}` (extras pass through- * `SeedApplyRequestSchema.loose()`); `packId` defaults to the registry- * default.- */- const handleSeedApply = withValidation(- SeedApplyRequestSchema,- async (_req, res, body) => {- // SeedApplyRequestSchema accepts `plan: unknown` (forward-compat); reject- // non-object payloads here so applySeed sees a structured value.- const planValue = body.plan;- if (!planValue || typeof planValue !== 'object') {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid plan payload.', {- handler: 'seed-apply',- });- return;- }- const plan = planValue as ScaffoldPlan;- // SeedApplyRequestSchema is `.loose()` so extras flow through as `unknown`- // on the parsed body; coerce defensively at the trust boundary. If the- // caller passed a non-empty `packId` that doesn't name a registered- // pack, reject explicitly (trust-boundary symmetry with the CLI, which- // returns an "Unknown pack" failure on the same input).- const looseBody = body as { packId?: unknown };- const rawPackId = looseBody.packId;- const packId = coercePackId(rawPackId);- if (typeof rawPackId === 'string' && rawPackId.length > 0 && packId === undefined) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Unknown packId.', {- handler: 'seed-apply',- detail: `Pack id "${rawPackId}" is not registered.`,- });- return;- }- try {- // The plan already has rootDir baked into its entries — apply only- // needs projectDir + packId (so it knows which template registry to- // resolve content from).- const result = await applySeed(plan, { projectDir: contentDir, packId });- successResponse(res, 200, SeedApplySuccessSchema, { result }, { handler: 'seed-apply' });- } catch (err) {- errorResponse(- res,- 500,- 'urn:ok:error:internal-server-error',- 'Failed to apply seed plan.',- {- handler: 'seed-apply',- cause: err,- },- );- }- },- {- handler: 'seed-apply',- method: 'POST',- preBodyGate: (req, res) => checkLocalOpSecurity(req, res, { handler: 'seed-apply' }),- },- );-- /**- * `POST /api/seed/install-pack-skill` — install only a pack's companion- * skills. It deliberately skips scaffold files and required-plugin changes:- * the settings card is a separate user-owned install action, not a replay of- * `ok seed` and not a side effect of the plugin toggle.- */- const handleSeedInstallPackSkill = withValidation(- SeedInstallPackSkillRequestSchema,- async (_req, res, body) => {- const packId = coercePackId(body.packId);- if (packId === undefined) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Unknown packId.', {- handler: 'seed-install-pack-skill',- detail: `Pack id "${body.packId}" is not registered.`,- });- return;- }- try {- const result = await installPackSkillOnDemand(contentDir, packId);- successResponse(res, 200, SeedInstallPackSkillSuccessSchema, result, {- handler: 'seed-install-pack-skill',- });- } catch (err) {- errorResponse(- res,- 500,- 'urn:ok:error:internal-server-error',- 'Failed to install pack skill.',- { handler: 'seed-install-pack-skill', cause: err },- );- }- },- {- handler: 'seed-install-pack-skill',- method: 'POST',- preBodyGate: (req, res) =>- checkLocalOpSecurity(req, res, { handler: 'seed-install-pack-skill' }),- },- );-- /**- * `GET /api/seed/packs` — enumerate available starter packs. Static data;- * no project context required. The picker UI fetches once on dialog mount.- * Delegates to the shared `listStarterPacks()` so HTTP + IPC return the- * same wire-format shape from one source.- */- async function handleSeedPacks(req: IncomingMessage, res: ServerResponse): Promise<void> {- if (!checkLocalOpSecurity(req, res, { handler: 'seed-packs' })) return;- if (req.method !== 'GET') {- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {- handler: 'seed-packs',- extraHeaders: { Allow: 'GET' },- });- return;- }- successResponse(- res,- 200,- SeedListPacksSuccessSchema,- { packs: listStarterPacks() },- { handler: 'seed-packs' },- );- }-/*** `POST /api/install-skill` — build `openknowledge.skill` and open it via* the OS file association so Claude Desktop's native install dialog takes@@ -11776,243 +11529,6 @@ export function createApiExtension(return { folderRel, resolvedContentDir };}- function validateTemplateName(name: string, res: ServerResponse, handler = 'template'): boolean {- if (!name || !TEMPLATE_NAME_REGEX.test(name)) {- errorResponse(- res,- 400,- 'urn:ok:error:invalid-request',- 'Invalid name: must be letters / digits / `_` / `-` only (no `.md` extension).',- { handler },- );- return false;- }- return true;- }-- /**- * Resolve a template by walking leaf → root from `folderRel`, closest-wins.- * Returns the matched file's abs path, the owning folder, and whether it's- * `local` (owned by `folderRel` itself) or `inherited` (from an ancestor).- * Single source of the resolution walk — shared by `handleTemplateGet` and- * the move handler's inherited-vs-absent disambiguation.- */- function findTemplateLeafToRoot(- resolvedContentDir: string,- folderRel: string,- name: string,- ): { abs: string; folder: string; scope: 'local' | 'inherited' } | null {- const segments = folderRel === '' ? [] : folderRel.split('/');- for (let depth = segments.length; depth >= 0; depth--) {- const ancestorFolder = depth === 0 ? '' : segments.slice(0, depth).join('/');- const ancestorAbs =- ancestorFolder === '' ? resolvedContentDir : resolve(resolvedContentDir, ancestorFolder);- if (- ancestorAbs !== resolvedContentDir &&- !ancestorAbs.startsWith(`${resolvedContentDir}${sep}`)- ) {- continue;- }- const candidate = resolve(ancestorAbs, '.ok', 'templates', `${name}.md`);- if (existsSync(candidate)) {- return {- abs: candidate,- folder: ancestorFolder,- scope: depth === segments.length ? 'local' : 'inherited',- };- }- }- return null;- }-- function pickFrontmatterFields(raw: unknown): Record<string, unknown> {- const out: Record<string, unknown> = {};- if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return out;- for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {- if (value === undefined) continue;- out[key] = value;- }- return out;- }-- const handleFolderConfigGet = withValidation(- EmptyRequestSchema,- async (req, res) => {- try {- const url = new URL(req.url ?? '', 'http://localhost');- const validated = validateFolderRel(- url.searchParams.get('path') ?? '',- res,- 'path',- 'folder-config-get',- );- if (!validated) return;- const meta = await enrichDirectory(validated.folderRel, {- projectDir: validated.resolvedContentDir,- });- const folderOkDir = resolve(validated.resolvedContentDir, validated.folderRel, '.ok');- const localFmPath = resolve(folderOkDir, 'frontmatter.yml');- let frontmatterLocal: Record<string, unknown> | null = null;- if (existsSync(localFmPath)) {- try {- const raw = await readFile(localFmPath, 'utf-8');- const parsed = parseYaml(raw);- if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {- frontmatterLocal = parsed as Record<string, unknown>;- } else {- frontmatterLocal = {};- }- } catch (err) {- const reason = err instanceof Error ? err.message : String(err);- log.warn(- { path: localFmPath, reason },- `[folder-config:get] malformed YAML in ${localFmPath}: ${reason}`,- );- frontmatterLocal = null;- }- }-- // Folder frontmatter is SELF-ONLY (no ancestor cascade) and there- // are no schema declarations — `frontmatter_local` is the folder's- // own open-shape frontmatter, the whole contract.- successResponse(- res,- 200,- FolderConfigGetSuccessSchema,- {- folder: meta,- frontmatter_local: frontmatterLocal,- },- { handler: 'folder-config-get' },- );- } catch (e) {- errorResponse(- res,- 500,- 'urn:ok:error:internal-server-error',- 'Failed to read folder config.',- { handler: 'folder-config-get', cause: e },- );- }- },- { handler: 'folder-config-get', method: 'GET', skipBodyParse: true },- );-- const handleFolderConfigPut = withValidation(- FolderConfigPutRequestSchema,- async (_req, res, body) => {- try {- // No-project single-file mode writes nothing into the user's directory- // beyond the one edited doc. Folder config would land a- // `<folder>/.ok/frontmatter.yml` sidecar in the user's tree — refuse.- if (ephemeral) {- errorResponse(- res,- 403,- 'urn:ok:error:single-file-mode',- 'Folder configuration is not available in single-file mode.',- { handler: 'folder-config-put' },- );- return;- }- const actor = extractActorIdentity(- body as unknown as Record<string, unknown>,- getPrincipal,- );- if (actor.kind === 'invalid-summary') {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {- handler: 'folder-config-put',- });- return;- }- const validated = validateFolderRel(body.path, res, 'path', 'folder-config-put');- if (!validated) return;-- // Write the folder's own frontmatter (open-shape, like a doc's) via the- // single-folder merge-patch helper — addressed by the folder's own- // path, no glob and no whitelist.- const allApplied: Array<{ path: string; action: 'written' | 'deleted' | 'noop' }> = [];- if (body.frontmatter !== undefined) {- const result = applyFolderFrontmatterPatch({- anchorDir: validated.resolvedContentDir,- folderRel: validated.folderRel,- patch: body.frontmatter,- });- if (!result.ok) {- const status = result.error.code === 'WRITE_ERROR' ? 500 : 400;- const urn =- status === 500- ? 'urn:ok:error:internal-server-error'- : 'urn:ok:error:invalid-request';- const title = status === 500 ? 'Failed to write folder config.' : result.error.message;- errorResponse(res, status, urn, title, {- handler: 'folder-config-put',- detail: result.error.code,- cause: new Error(result.error.message),- });- return;- }- allApplied.push({ path: result.path, action: result.action });- // Attribute the frontmatter change (skip a no-op patch).- if (result.action !== 'noop') {- attributeOkArtifactWrite(- actor,- okArtifactKey('folder-frontmatter', validated.folderRel),- `folder-frontmatter-${result.action === 'deleted' ? 'delete' : 'edit'}: ${result.path}`,- );- scheduleOkArtifactFlush('folder-config-put');- }- }-- successResponse(- res,- 200,- FolderConfigPutSuccessSchema,- { applied: allApplied },- { handler: 'folder-config-put' },- );- } catch (e) {- errorResponse(- res,- 500,- 'urn:ok:error:internal-server-error',- 'Failed to write folder config.',- { handler: 'folder-config-put', cause: e },- );- }- },- { handler: 'folder-config-put', method: 'PUT' },- );-- const handleFolderConfig = methodRouter(- { GET: handleFolderConfigGet, PUT: handleFolderConfigPut },- { handler: 'folder-config' },- );-- /**- * Conflict-aware refusal helper for the template handlers. A template is a- * content doc now (`<folder>/.ok/templates/<name>`), so its live Y.Doc carries- * a `lifecycle.status` Y.Map — a mutation against one mid-conflict must refuse- * exactly like the sibling content-write handlers, whose paired-write path- * (`composeAndWriteRawBody`) would otherwise clobber a doc the user is- * mid-resolving. Takes the pre-resolved content doc name — same shape as the- * sibling `checkSkillDocConflictGate`, so the two gates read as one pattern.- * Returns `true` when the gate fired (caller short-circuits); `false` when- * the mutation may proceed.- */- function checkTemplateConflictGate(- templateDocName: string,- handler: 'template-put' | 'template-delete' | 'template-move' | 'template-import',- res: ServerResponse,- ): boolean {- const doc = hocuspocus.documents.get(templateDocName);- if (doc && isDocInConflict(doc)) {- respondDocInConflict(res, new DocInConflictError({ file: `${templateDocName}.md` }), handler);- return true;- }- return false;- }-/*** Conflict-aware refusal for the skill CONTENT-doc writers. A PROJECT skill's* `SKILL.md` and its `.md` references are real CRDT content docs (skills-as-@@ -12051,824 +11567,36 @@ export function createApiExtension(return { frontmatter: parseFrontmatterRecord(raw) ?? {}, body };};- const handleTemplateGet = withValidation(- EmptyRequestSchema,- async (req, res) => {- try {- const url = new URL(req.url ?? '', 'http://localhost');- const name = url.searchParams.get('name') ?? '';- if (!validateTemplateName(name, res, 'template-get')) return;-- // Walk leaf → root for closest match.- const validated = validateFolderRel(- url.searchParams.get('folder') ?? '',- res,- 'folder',- 'template-get',- );- if (!validated) return;- const { folderRel, resolvedContentDir } = validated;-- const found = findTemplateLeafToRoot(resolvedContentDir, folderRel, name);- if (!found) {- errorResponse(res, 404, 'urn:ok:error:template-not-found', 'Template not found.', {- handler: 'template-get',- detail: `Template "${name}" not found for folder "${folderRel || '.'}". Walked leaf → root.`,- });- return;- }- const { abs: foundAbs, folder: foundFolder, scope: foundScope } = found;-- const raw = await readFile(foundAbs, 'utf-8');- // Normalize single-block (and legacy two-block) templates: wire- // `frontmatter` = the template's identity (title/description), wire- // `body` = the starter content (doc-frontmatter block + markdown) a- // new doc receives. Tokens (`{{date}}`) are preserved verbatim.- const model = parseTemplateFile(raw);- const frontmatter = model.identity as Record<string, unknown>;- const body = model.starterContent;+ // ─── Skills (`/api/skill`, `/api/skills`) ──────────────────────+ //+ // Skills are fs-direct `.ok/skills/<name>/` artifacts (SKILL.md + optional+ // references/scripts), NON-CRDT, addressed by scope + name (no per-folder+ // leaf-to-root walk — a skill's name is its whole identity). They reuse the+ // template artifact spine: server-routed, actor-attributed, shadow-repo+ // committed via `attributeOkArtifactWrite` + `commitOkArtifactWrite`.+ // Project scope only this slice; global scope (a user-level store)+ // is gated on the not-yet-built device-sync mechanism and refused with a+ // teaching error rather than silently writing to an unmanaged path.+ const SKILLS_LIST_CAP = 500;- const relPath = relative(resolvedContentDir, foundAbs)- .split(/[\\/]/)- .filter(Boolean)- .join('/');-- successResponse(- res,- 200,- TemplateGetSuccessSchema,- {- template: {- name,- folder: foundFolder,- scope: foundScope,- path: relPath,- frontmatter,- body,- },- },- { handler: 'template-get' },- );- } catch (e) {- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to read template.', {- handler: 'template-get',- cause: e,- });- }- },- { handler: 'template-get', method: 'GET', skipBodyParse: true },- );-- const handleTemplatePut = withValidation(- TemplatePutRequestSchema,- async (_req, res, body) => {- try {- // Templates write `<folder>/.ok/templates/*.md` into the content tree —- // a user-dir artifact single-file mode must never create.- if (ephemeral) {- errorResponse(- res,- 403,- 'urn:ok:error:single-file-mode',- 'Templates are not available in single-file mode.',- { handler: 'template-put' },- );- return;- }- const actor = extractActorIdentity(- body as unknown as Record<string, unknown>,- getPrincipal,- );- if (actor.kind === 'invalid-summary') {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {- handler: 'template-put',- });- return;- }- const name = body.name;- if (!validateTemplateName(name, res, 'template-put')) return;- const validated = validateFolderRel(body.folder, res, 'folder', 'template-put');- if (!validated) return;-- // Conflict-aware refusal. See `checkTemplateConflictGate`.- if (- checkTemplateConflictGate(- templateDocNameFor(validated.folderRel, name),- 'template-put',- res,- )- )- return;-- // Compose + validate the `.md` bytes server-side, then route the body- // through the template's CRDT doc (precedent #24 / #38) — same shape as- // skill-put. Templates are content docs, so the ordinary content- // persistence path (not the managed-artifact branch) writes the file.- const composed = composeTemplateContent({- name,- body: typeof body.body === 'string' ? body.body : '',- frontmatter: pickFrontmatterFields(body.frontmatter) satisfies TemplateFrontmatter,- });- if (!composed.ok) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid template request.', {- handler: 'template-put',- detail: composed.error.code,- cause: new Error(composed.error.message),- });- return;- }-- const templateFilePath = resolve(- validated.resolvedContentDir,- validated.folderRel,- '.ok',- 'templates',- `${name}.md`,- );- const templateCreated = !existsSync(templateFilePath);- const templateRelPath = relative(validated.resolvedContentDir, templateFilePath)- .split(/[\\/]/)- .filter(Boolean)- .join('/');- const templateDocName = templateDocNameFor(validated.folderRel, name);-- const { agentId, agentName, colorSeed, clientName } = extractAgentIdentity(- body as unknown as Record<string, unknown>,- );- const templateSession = await sessionManager.getSession(templateDocName, agentId, {- displayName: agentName,- colorSeed,- clientName,- });- templateSession.dc.document.transact(() => {- composeAndWriteRawBody(templateSession.dc.document, composed.content, 'agent');- }, templateSession.origin);-- const templateFlush = await flushDiskAndDetectOutcome(templateDocName);- if (templateFlush?.kind === 'failure') {- respondPersistenceFailure(res, templateFlush.failure, 'template-put');- return;- }- if (templateFlush?.kind === 'divergence') {- respondDiskDivergence(res, 'template-put');- return;- }-- // Close the dropped-FSEvent gap at the source (see helper): the flush- // may have just created this folder's `.ok/templates/` dir — exactly- // the brand-new-subdir race where the watcher's create event can be- // lost. Same net as the sibling agent-write handlers.- registerWrittenDocInFileIndex(templateDocName, composed.content);-- attributeOkArtifactWrite(- actor,- okArtifactKey('template', validated.folderRel, name),- `${templateCreated ? 'template-create' : 'template-edit'}: ${templateRelPath}`,- );- scheduleOkArtifactFlush('template-put');- successResponse(- res,- 200,- TemplatePutSuccessSchema,- {- path: templateRelPath,- created: templateCreated,- warnings: composed.warnings,- },- { handler: 'template-put' },- );- } catch (e) {- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to write template.', {- handler: 'template-put',- cause: e,- });- }- },- { handler: 'template-put', method: 'PUT' },- );-- const handleTemplateDelete = withValidation(- EmptyRequestSchema,- async (req, res) => {- try {- const url = new URL(req.url ?? '', 'http://localhost');- const name = url.searchParams.get('name') ?? '';- if (!validateTemplateName(name, res, 'template-delete')) return;- const validated = validateFolderRel(- url.searchParams.get('folder') ?? '',- res,- 'folder',- 'template-delete',- );- if (!validated) return;-- // DELETE has no body (query-param transport); read identity + summary- // from the query string into a synthetic body for extractActorIdentity.- const actor = extractActorIdentityFromQuery(url, getPrincipal);- if (actor.kind === 'invalid-summary') {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {- handler: 'template-delete',- });- return;- }-- // Conflict-aware refusal. See `checkTemplateConflictGate`.- if (- checkTemplateConflictGate(- templateDocNameFor(validated.folderRel, name),- 'template-delete',- res,- )- )- return;-- // Tear down the live template content doc (if open) BEFORE removing the- // file, so its debounced content store can't re-store (resurrect) it on- // a later unload. Same spine doc-delete + skill-delete use; no-op when- // the doc was never opened.- await captureAndCloseDocuments(- [templateDocNameFor(validated.folderRel, name)],- 'deleted-upstream',- );-- const deleteInput: Parameters<typeof applyTemplateDelete>[0] = {- projectDir: validated.resolvedContentDir,- folder: validated.folderRel,- name,- };- const result = applyTemplateDelete(deleteInput);- if (!result.ok) {- const status =- result.error.code === 'WRITE_ERROR' ||- result.error.code === 'UNLINK_FAILED' ||- result.error.code === 'BAD_PROJECT_DIR'- ? 500- : 400;- const urn =- status === 500 ? 'urn:ok:error:internal-server-error' : 'urn:ok:error:invalid-request';- const title = status === 500 ? 'Failed to delete template.' : 'Invalid template request.';- errorResponse(res, status, urn, title, {- handler: 'template-delete',- detail: result.error.code,- cause: new Error(result.error.message),- });- return;- }- // Only attribute when a file was actually removed (no-op delete of an- // absent template records nothing).- if (result.existed) {- attributeOkArtifactWrite(- actor,- okArtifactKey('template', validated.folderRel, name),- `template-delete: ${result.path}`,- );- scheduleOkArtifactFlush('template-delete');- // Mark the content doc removed so a stale tab redirects instead of- // offering to resurrect it (parity with ordinary doc deletion).- recentlyRemovedDocs?.setDeleted(templateDocNameFor(validated.folderRel, name));- }- successResponse(- res,- 200,- TemplateDeleteSuccessSchema,- { existed: result.existed, path: result.path },- { handler: 'template-delete' },- );- } catch (e) {- errorResponse(- res,- 500,- 'urn:ok:error:internal-server-error',- 'Failed to delete template.',- { handler: 'template-delete', cause: e },- );- }- },- { handler: 'template-delete', method: 'DELETE', skipBodyParse: true },- );-- const handleTemplateMove = withValidation(- TemplateMoveRequestSchema,- async (_req, res, body) => {- try {- const actor = extractActorIdentity(- body as unknown as Record<string, unknown>,- getPrincipal,- );- if (actor.kind === 'invalid-summary') {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {- handler: 'template-move',- });- return;- }- if (!validateTemplateName(body.fromName, res, 'template-move')) return;- if (!validateTemplateName(body.toName, res, 'template-move')) return;- const fromValidated = validateFolderRel(body.fromFolder, res, 'folder', 'template-move');- if (!fromValidated) return;- const toValidated = validateFolderRel(body.toFolder, res, 'folder', 'template-move');- if (!toValidated) return;-- // Refuse moving a source whose target doc is in an unresolved conflict.- if (- checkTemplateConflictGate(- templateDocNameFor(fromValidated.folderRel, body.fromName),- 'template-move',- res,- )- ) {- return;- }-- // Tear down the live source template content doc (if open) BEFORE the- // git-mv relocates the file — otherwise its debounced content store- // would re-store at the now-stale from-path, resurrecting the moved- // template.- await captureAndCloseDocuments(- [templateDocNameFor(fromValidated.folderRel, body.fromName)],- 'renamed',- );-- const result = await applyTemplateMove({- projectDir: fromValidated.resolvedContentDir,- fromFolder: fromValidated.folderRel,- fromName: body.fromName,- toFolder: toValidated.folderRel,- toName: body.toName,- // git mv (history-preserving) when the path is tracked; plain disk- // rename otherwise. `withParentLock` inside renameTrackedPathInGit- // serializes against concurrent doc renames (git-index safety).- relocate: async (fromAbs, toAbs) => {- const movedWithGit = await renameTrackedPathInGit(projectDir, fromAbs, toAbs);- if (!movedWithGit) renamePathOnDisk(fromAbs, toAbs);- return movedWithGit;- },- });-- if (!result.ok) {- if (result.error.code === 'TEMPLATE_NOT_FOUND') {- // Distinguish "inherited" (resolvable from an ancestor) — teach- // localize-then-move — from "truly absent" — 404.- const found = findTemplateLeafToRoot(- fromValidated.resolvedContentDir,- fromValidated.folderRel,- body.fromName,- );- if (found?.scope === 'inherited') {- errorResponse(- res,- 400,- 'urn:ok:error:invalid-request',- `Template "${body.fromName}" is inherited from "${found.folder || '(root)'}", not local to "${fromValidated.folderRel || '(root)'}". Move it from the folder that owns it, or create a local copy here first (then move that).`,- { handler: 'template-move', detail: 'TEMPLATE_INHERITED' },- );- return;- }- errorResponse(res, 404, 'urn:ok:error:template-not-found', 'Template not found.', {- handler: 'template-move',- detail: result.error.message,- });- return;- }- if (result.error.code === 'TEMPLATE_EXISTS') {- errorResponse(res, 409, 'urn:ok:error:doc-already-exists', result.error.message, {- handler: 'template-move',- detail: result.error.code,- });- return;- }- const status =- result.error.code === 'WRITE_ERROR' || result.error.code === 'MOVE_FAILED' ? 500 : 400;- errorResponse(- res,- status,- status === 500 ? 'urn:ok:error:internal-server-error' : 'urn:ok:error:invalid-request',- status === 500 ? 'Failed to move template.' : 'Invalid template move request.',- {- handler: 'template-move',- detail: result.error.code,- cause: new Error(result.error.message),- },- );- return;- }-- // Mark the source content doc removed (the move relocated its file) so a- // stale tab on the old name redirects instead of offering to resurrect- // it (parity with ordinary doc deletion).- recentlyRemovedDocs?.setDeleted(templateDocNameFor(fromValidated.folderRel, body.fromName));-- // Optional atomic move+edit: rewrite the relocated template's content.- // The move already succeeded and persisted the original content, so any- // failure here is captured and reported AFTER the move is attributed —- // the rename must not be lost because the edit step failed.- let contentEditError: { code: string; message: string } | null = null;- if (body.body !== undefined || body.frontmatter !== undefined) {- // Preserve the existing (just-moved) body when only `frontmatter` is- // supplied. If that body can't be read, SKIP the rewrite rather than- // risk wiping it — defaulting to '' would re-introduce the body-loss- // bug on a read error; the moved file keeps its original content.- let writeBody: string | null;- if (typeof body.body === 'string') {- writeBody = body.body;- } else {- try {- writeBody = instantiateDoc(- readFileSync(resolve(toValidated.resolvedContentDir, result.toPath), 'utf-8'),- );- } catch {- writeBody = null;- }- }- if (writeBody === null) {- contentEditError = {- code: 'READ_FAILED',- message:- 'could not read the moved template to apply the metadata change; the move succeeded with the original content intact — retry the edit',- };- } else {- const writeResult = applyTemplateWrite({- projectDir: toValidated.resolvedContentDir,- folder: toValidated.folderRel,- name: body.toName,- body: writeBody,- frontmatter: pickFrontmatterFields(body.frontmatter) satisfies TemplateFrontmatter,- });- if (!writeResult.ok) contentEditError = writeResult.error;- }- }-- // Close the dropped-FSEvent gap for the DESTINATION (parity with- // put/import): the relocate may have just created `toFolder`'s- // `.ok/templates/` dir — the brand-new-subdir race where the watcher's- // create event can be lost. Read the final on-disk bytes (post the- // optional edit above) so the index entry matches what landed.- // Best-effort like the helper itself: on a read failure the CRDT/disk- // copy exists regardless and a rescan re-seeds the index.- try {- registerWrittenDocInFileIndex(- templateDocNameFor(toValidated.folderRel, body.toName),- readFileSync(resolve(toValidated.resolvedContentDir, result.toPath), 'utf-8'),- );- } catch {- // Unreadable destination — leave index membership to the watcher.- }-- // The move succeeded — attribute + commit + signal regardless of the- // optional content edit's outcome, so the rename is never lost when the- // edit step fails.- attributeOkArtifactWrite(- actor,- okArtifactKey('template', toValidated.folderRel, body.toName),- `template-rename: ${result.fromPath} -> ${result.toPath}`,- [{ from: result.fromPath, to: result.toPath }],- );- scheduleOkArtifactFlush('template-move');- signalChannel?.('files');-- if (contentEditError) {- const isServerError =- contentEditError.code === 'WRITE_ERROR' || contentEditError.code === 'READ_FAILED';- errorResponse(- res,- isServerError ? 500 : 400,- isServerError ? 'urn:ok:error:internal-server-error' : 'urn:ok:error:invalid-request',- // Include the destination so the agent can retry the content edit- // against the moved template without re-deriving where it landed.- `Template moved to "${result.toPath}", but updating its content failed.`,- {- handler: 'template-move',- detail: contentEditError.code,- cause: new Error(contentEditError.message),- },- );- return;- }- successResponse(- res,- 200,- TemplateMoveSuccessSchema,- { from: result.fromPath, to: result.toPath, committed: result.committed },- { handler: 'template-move' },- );- } catch (e) {- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to move template.', {- handler: 'template-move',- cause: e,- });- }- },- { handler: 'template-move', method: 'POST' },- );-- const handleTemplate = methodRouter(- {- GET: handleTemplateGet,- PUT: handleTemplatePut,- POST: handleTemplateMove,- DELETE: handleTemplateDelete,- },- { handler: 'template' },- );-- const handleTemplateImport = withValidation(- TemplateImportRequestSchema,- async (_req, res, body) => {- try {- if (ephemeral) {- errorResponse(- res,- 403,- 'urn:ok:error:single-file-mode',- 'Templates are not available in single-file mode.',- { handler: 'template-import' },- );- return;- }-- const actor = extractActorIdentity(- body as unknown as Record<string, unknown>,- getPrincipal,- );- if (actor.kind === 'invalid-summary') {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {- handler: 'template-import',- });- return;- }-- const sourcePath = body.sourcePath;- if (!isSafeDocName(sourcePath)) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid sourcePath.', {- handler: 'template-import',- });- return;- }-- const sourceDocName = resolveAlias(sourcePath);- if (isSystemDoc(sourceDocName) || isConfigDoc(sourceDocName)) {- errorResponse(- res,- 400,- 'urn:ok:error:reserved-doc-name',- `'${sourceDocName}' is a reserved document name.`,- { handler: 'template-import' },- );- return;- }-- const sourceFilePath = resolveContentEntryPath(contentDir, 'file', sourceDocName);- if (!existsSync(sourceFilePath)) {- errorResponse(- res,- 404,- 'urn:ok:error:doc-not-found',- `Source document not found: ${sourceDocName}.`,- {- handler: 'template-import',- },- );- return;- }-- const existing = hocuspocus.documents.get(sourceDocName);- if (body.deleteSource) {- const deleteEngine = getSyncEngine?.();- const deleteTrackedFiles = new Set(- deleteEngine ? deleteEngine.getConflicts().map((c) => c.file) : [],- );- const conflictedByLifecycle = existing !== undefined && isDocInConflict(existing);- const conflictedByStore = deleteTrackedFiles.has(sourcePath);- if (conflictedByLifecycle || conflictedByStore) {- respondDocInConflict(- res,- new DocInConflictError({ file: sourcePath }),- 'template-import',- );- return;- }- }-- // Read source content- let sourceContent = '';- if (existing) {- sourceContent = existing.getText('source').toString();- } else {- const dc = await hocuspocus.openDirectConnection(sourceDocName);- try {- const document = dc.document;- if (!document) {- errorResponse(- res,- 500,- 'urn:ok:error:doc-not-available',- 'Source document is not available.',- {- handler: 'template-import',- },- );- return;- }- sourceContent = document.getText('source').toString();- } finally {- await dc.disconnect();- }- }-- // Determine target template name- let name = body.name;- if (!name) {- const { basename } = splitContentPath(sourcePath);- const nameWithoutExt = basename.replace(/\.(md|mdx)$/i, '');- name = nameWithoutExt.replace(/[^A-Za-z0-9_-]/g, '-').toLowerCase();- name = name.replace(/^[-_]+|[-_]+$/g, '');- name ||= 'imported-template';- }-- if (!validateTemplateName(name, res, 'template-import')) return;-- const validated = validateFolderRel(body.targetFolder, res, 'folder', 'template-import');- if (!validated) return;-- if (- checkTemplateConflictGate(- templateDocNameFor(validated.folderRel, name),- 'template-import',- res,- )- )- return;-- // Parse existing frontmatter of the source file to extract the title/description/tags- const { frontmatter: sourceFmText, body: sourceBody } = stripFrontmatter(sourceContent);- const cleanFmText = unwrapFrontmatterFences(sourceFmText);- let sourceFmObj: Record<string, unknown> = {};- try {- if (cleanFmText.trim()) {- sourceFmObj = parseYaml(cleanFmText) as Record<string, unknown>;- }- } catch {- // Malformed frontmatter — treat the source as having none.- }-- const templateTitle =- body.title || (sourceFmObj?.title as string) || extractPageTitle(sourceContent, name);- const templateDescription = (sourceFmObj?.description as string) || '';- const templateTags = Array.isArray(sourceFmObj?.tags) ? (sourceFmObj.tags as string[]) : [];-- // For the starter content, we can use the original document frontmatter but remove `template:`- // if it somehow got there. Keep other fields. We also drop `title` so it doesn't get baked into every instance.- const starterFmObj = { ...sourceFmObj };- delete starterFmObj.template;- delete starterFmObj.title;-- let starterContent = '';- if (Object.keys(starterFmObj).length > 0) {- const fmYaml = stringifyYaml(starterFmObj);- starterContent = `${fmYaml.trim()}\n`;- }- starterContent = starterContent ? `---\n${starterContent}---\n${sourceBody}` : sourceBody;-- const composed = composeTemplateContent({- name,- body: starterContent,- frontmatter: {- title: templateTitle,- description: templateDescription,- tags: templateTags,- },- });-- if (!composed.ok) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid template request.', {- handler: 'template-import',- detail: composed.error.code,- cause: new Error(composed.error.message),- });- return;- }-- const templateFilePath = resolve(- validated.resolvedContentDir,- validated.folderRel,- '.ok',- 'templates',- `${name}.md`,- );- const templateCreated = !existsSync(templateFilePath);- const templateRelPath = relative(validated.resolvedContentDir, templateFilePath)- .split(/[\\/]/)- .filter(Boolean)- .join('/');- const templateDocName = templateDocNameFor(validated.folderRel, name);-- const { agentId, agentName, colorSeed, clientName } = extractAgentIdentity(- body as unknown as Record<string, unknown>,- );- const templateSession = await sessionManager.getSession(templateDocName, agentId, {- displayName: agentName,- colorSeed,- clientName,- });- templateSession.dc.document.transact(() => {- composeAndWriteRawBody(templateSession.dc.document, composed.content, 'agent');- }, templateSession.origin);-- const templateFlush = await flushDiskAndDetectOutcome(templateDocName);- if (templateFlush?.kind === 'failure') {- respondPersistenceFailure(res, templateFlush.failure, 'template-import');- return;- }- if (templateFlush?.kind === 'divergence') {- respondDiskDivergence(res, 'template-import');- return;- }-- // Close the dropped-FSEvent gap at the source (see helper): the flush- // may have just created the target folder's `.ok/templates/` dir —- // exactly the brand-new-subdir race where the watcher's create event- // can be lost. Same net as the sibling agent-write handlers.- registerWrittenDocInFileIndex(templateDocName, composed.content);-- attributeOkArtifactWrite(- actor,- okArtifactKey('template', validated.folderRel, name),- `template-import: ${templateRelPath}`,- );-- if (body.deleteSource) {- const deletedDocNames = [sourceDocName];- await captureAndCloseDocuments(deletedDocNames, 'deleted-upstream');- if (recentlyRemovedDocs) {- recentlyRemovedDocs.setDeleted(sourceDocName);- }- tracedUnlinkSync(sourceFilePath);- mutateFileIndex?.({- kind: 'delete',- path: sourceFilePath,- docName: sourceDocName,- });- }-- scheduleOkArtifactFlush('template-import');- signalChannel?.('files');-- successResponse(- res,- 200,- TemplateImportSuccessSchema,- {- path: templateRelPath,- created: templateCreated,- warnings: composed.warnings,- },- { handler: 'template-import' },- );- } catch (e) {- errorResponse(- res,- 500,- 'urn:ok:error:internal-server-error',- 'Failed to import template.',- {- handler: 'template-import',- cause: e,- },- );- }- },- { handler: 'template-import', method: 'POST' },- );-- // ─── Skills (`/api/skill`, `/api/skills`) ──────────────────────- //- // Skills are fs-direct `.ok/skills/<name>/` artifacts (SKILL.md + optional- // references/scripts), NON-CRDT, addressed by scope + name (no per-folder- // leaf-to-root walk — a skill's name is its whole identity). They reuse the- // template artifact spine: server-routed, actor-attributed, shadow-repo- // committed via `attributeOkArtifactWrite` + `commitOkArtifactWrite`.- // Project scope only this slice; global scope (a user-level store)- // is gated on the not-yet-built device-sync mechanism and refused with a- // teaching error rather than silently writing to an unmanaged path.- const SKILLS_LIST_CAP = 500;-- // The shape check on its own, for callers that classify a name per row rather- // than answering the request with a 400 (bulk verbs).- function isValidSkillName(name: string): boolean {- return Boolean(name) && name.length <= 64 && SKILL_NAME_REGEX.test(name);- }- function validateSkillName(name: string, res: ServerResponse, handler: string): boolean {- if (!isValidSkillName(name)) {- errorResponse(- res,- 400,- 'urn:ok:error:invalid-request',- 'Invalid skill name: lowercase letters, digits, and hyphens only (≤64 chars; no slashes, dots, spaces, or uppercase).',- { handler },- );- return false;- }- return true;- }+ // The shape check on its own, for callers that classify a name per row rather+ // than answering the request with a 400 (bulk verbs).+ function isValidSkillName(name: string): boolean {+ return Boolean(name) && name.length <= 64 && SKILL_NAME_REGEX.test(name);+ }+ function validateSkillName(name: string, res: ServerResponse, handler: string): boolean {+ if (!isValidSkillName(name)) {+ errorResponse(+ res,+ 400,+ 'urn:ok:error:invalid-request',+ 'Invalid skill name: lowercase letters, digits, and hyphens only (≤64 chars; no slashes, dots, spaces, or uppercase).',+ { handler },+ );+ return false;+ }+ return true;+ }/** Parse the `scope` query param (defaults to `project`); 400s on a bad value. */function parseSkillScope(@@ -13531,16 +12259,6 @@ export function createApiExtension(return true;}- /**- * The CRDT doc name a template opens/persists under — its content-relative path- * (`<folderRel>/.ok/templates/<name>`, ext-less, RAW). Delegates to the core- * builder so server handlers, the client open path, and the properties panel- * share one identity. `''` folder → `.ok/templates/<name>` (project root).- */- function templateDocNameFor(folderRel: string, name: string): string {- return templateContentDocName(folderRel, name);- }-/*** POSIX store-relative path for a skill file. Project skills are reported* relative to `contentDir` (→ `.ok/skills/<name>/SKILL.md`); global skills@@ -19135,66 +17853,6 @@ export function createApiExtension(});searchService.prewarm();- async function handleHandoffDispatchRoute(- req: IncomingMessage,- res: ServerResponse,- ): Promise<void> {- // Loopback-only gate — spawns binaries on the user's machine. Same model- // as `/api/spawn-cursor` and `/api/installed-agents`. The handler also- // enforces app-name allowlist + URL scheme matching + cursor path- // containment as defense-in-depth.- if (!checkLocalOpSecurity(req, res, { handler: 'handoff' })) return;- try {- await handleHandoffDispatch(req, res, {- contentDir,- platform: process.platform,- // Share the same cached scheme probe `/api/installed-agents` uses so- // the Windows/Linux dispatch availability gate agrees with the- // dropdown's render gate (and reuses its 60s TTL — the row the user- // just saw enabled decides the click). Unused on macOS.- isSchemeRegistered: installedAgentsCache.probeWithCache,- });- } catch (e) {- if (!res.headersSent) {- log.error({ err: e, requestId: getRequestId(req) }, '[handoff] route wrapper failed');- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'handoff',- cause: e,- });- }- }- }-- async function handleSpawnCursorRoute(req: IncomingMessage, res: ServerResponse): Promise<void> {- // Same loopback + DNS-rebinding gate as `/api/installed-agents` — this- // endpoint spawns a binary on the user's machine, so confining callers- // to same-origin loopback is load-bearing. Path containment + hardcoded- // `cursor` binary + `shell:false` argv-array enforce the rest of the- // security model inside `handleSpawnCursor`. See the file-level comment- // in `./spawn-cursor-api.ts` for the full threat model.- // `checkLocalOpSecurity` itself emits RFC 9457 problem+json on rejection.- if (!checkLocalOpSecurity(req, res, { handler: 'spawn-cursor' })) return;- try {- await handleSpawnCursor(req, res, {- contentDir,- platform: process.platform,- });- } catch (e) {- // Defensive: `handleSpawnCursor` emits RFC 9457 problem+json for every- // expected failure mode internally. This catches truly unexpected- // throws (e.g., a `resolveCursorBinary` injection that throws- // synchronously) so the client still receives a typed contract- // response instead of a hung connection. Mirrors `handleInstalledAgentsRoute`.- if (!res.headersSent) {- log.error({ err: e, requestId: getRequestId(req) }, '[spawn-cursor] route wrapper failed');- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'spawn-cursor',- cause: e,- });- }- }- }-/*** `POST /api/share/construct-url` — read the project's local git state and* emit a marketing-safe share URL (`https://openknowledge.ai/d/<base64url>`)@@ -19934,74 +18592,6 @@ export function createApiExtension(},);- // Web/browser client-log ingest: the renderer forwarder POSTs batches of- // captured `console` output here, written to the `renderer` pino subsystem- // (→ the local-sink server log). Electron captures renderer console in its- // main process instead. Writes no Y.Docs — exempt from attribution; gated by- // `checkLocalOpSecurity` (loopback + Host + Origin) like the local-op routes.- const handleClientLogs = withValidation(- ClientLogsRequestSchema,- async (_req, res, body) => {- try {- const logger = getLogger('renderer');- if (body.droppedSinceLastFlush !== undefined && body.droppedSinceLastFlush > 0) {- // Gap marker: the forwarder lost entries (buffer overflow / failed- // POSTs) between the previous delivered batch and this one. Persist- // it as its own line so a log reader knows the silence was loss,- // not inactivity.- logger.warn(- {- source: 'renderer-console',- transport: 'web',- event: 'client-log-entries-dropped',- droppedSinceLastFlush: body.droppedSinceLastFlush,- },- 'client-log-entries-dropped',- );- }- for (const entry of body.entries) {- // Per-entry guard: one entry that trips a pino serialization fault- // must not drop the rest of the batch (the response still reports the- // full accepted count — best-effort diagnostics ingest).- try {- // Spread client `fields` FIRST so the provenance markers below- // always win (a client field must not clobber source/transport).- logger[entry.level](- {- ...entry.fields,- source: 'renderer-console',- transport: 'web',- ...(entry.sourceId ? { sourceId: entry.sourceId } : {}),- ...(entry.lineNumber !== undefined ? { lineNumber: entry.lineNumber } : {}),- ...(entry.ts !== undefined ? { clientTs: entry.ts } : {}),- },- entry.event ?? entry.message,- );- } catch {- // Skip the malformed entry; continue the batch.- }- }- successResponse(- res,- 200,- ClientLogsSuccessSchema,- { accepted: body.entries.length },- { handler: 'client-logs' },- );- } catch (err) {- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'client-logs',- cause: err,- });- }- },- {- handler: 'client-logs',- method: 'POST',- preBodyGate: (req, res) => checkLocalOpSecurity(req, res, { handler: 'client-logs' }),- },- );-// ───────────────────── Embeddings API key — Account control ─────────────────// Loopback + Origin gated (checkLocalOpSecurity) set/clear for the// machine-global embeddings key. The key travels renderer → loopback POST body@@ -20772,9 +19362,6 @@ export function createApiExtension('/api/comment': handleCommentRoute,'/api/asset': handleAsset,'/api/asset-text': handleAssetText,- '/api/folder-config': handleFolderConfig,- '/api/template': handleTemplate,- '/api/template/import': handleTemplateImport,'/api/skill': handleSkill,'/api/skill-file': handleSkillFile,'/api/skill-file/rename': handleSkillFileRename,@@ -20839,14 +19426,7 @@ export function createApiExtension('/api/local-op/embeddings/set-key': handleLocalOpEmbeddingsSetKey,'/api/local-op/embeddings/clear-key': handleLocalOpEmbeddingsClearKey,'/api/local-op/embeddings/test': handleLocalOpEmbeddingsTest,- '/api/spawn-cursor': handleSpawnCursorRoute,- '/api/handoff': handleHandoffDispatchRoute,'/api/install-skill': handleInstallSkill,- '/api/seed/plan': handleSeedPlan,- '/api/seed/apply': handleSeedApply,- '/api/seed/install-pack-skill': handleSeedInstallPackSkill,- '/api/seed/packs': handleSeedPacks,- '/api/client-logs': handleClientLogs,};if (enableTestRoutes) {@@ -20892,9 +19472,6 @@ export function createApiExtension('/api/test-rescan-backlinks','/api/test-rescan-files','/api/install-skill',- '/api/folder-config',- '/api/template',- '/api/template/import','/api/skill','/api/skill-file','/api/skill-file/rename',@@ -20911,9 +19488,6 @@ export function createApiExtension('/api/skills/reimport-bulk','/api/skill/revert','/api/skill/track-in-git',- '/api/seed/apply',- '/api/seed/install-pack-skill',- '/api/client-logs',]);// Every `/api/local-op/*` endpoint mutates local filesystem state or// issues network requests on behalf of the user — clone/open/auth@@ -21052,6 +19626,46 @@ export function createApiExtension(getGeneratedIndexSettingsStatus,setGeneratedIndexEnabled,});+ const seedRoutes = createSeedRoutes({+ contentDir,+ checkLocalOpSecurity,+ });+ const systemActionsRoutes = createSystemActionsRoutes({+ contentDir,+ log,+ checkLocalOpSecurity,+ installedAgentsCache,+ });+ const folderTemplateRoutes = createFolderTemplateRoutes({+ contentDir,+ projectDir,+ ephemeral,+ log,+ hocuspocus,+ sessionManager,+ getPrincipal,+ signalChannel,+ getSyncEngine,+ recentlyRemovedDocs,+ isSafeDocName,+ resolveAlias,+ resolveContentEntryPath,+ validateFolderRel,+ extractAgentIdentity,+ extractActorIdentityFromQuery,+ okArtifactKey,+ attributeOkArtifactWrite,+ scheduleOkArtifactFlush,+ flushDiskAndDetectOutcome,+ respondPersistenceFailure,+ respondDiskDivergence,+ registerWrittenDocInFileIndex,+ captureAndCloseDocuments,+ renameTrackedPathInGit,+ renamePathOnDisk,+ splitContentPath,+ mutateFileIndex,+ });const nativeGroups = [linkGraphRoutes,metricsRoutes,@@ -21062,6 +19676,9 @@ export function createApiExtension(skillsReadRoutes,skillsShRoutes,workspaceToolsRoutes,+ seedRoutes,+ systemActionsRoutes,+ folderTemplateRoutes,];// "A route lives in exactly one router" — enforced at construction, not// just documented; covers every group aggregated into the native paths.diff --git a/packages/server/src/api-folder-template-composition.test.ts b/packages/server/src/api-folder-template-composition.test.tsnew file mode 100644index 000000000..a0afebdaf--- /dev/null+++ b/packages/server/src/api-folder-template-composition.test.ts@@ -0,0 +1,125 @@+import { mkdtempSync, writeFileSync } from 'node:fs';+import { mkdtemp, rm } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { resolve } from 'node:path';+import { afterAll, beforeAll, describe, expect, test } from 'vitest';+import type { BootedServer } from './boot.ts';+import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.test-helper.ts';++/**+ * Characterization: the natively-routed folder-template group+ * (`folder-config` GET+PUT, `template` GET/PUT/POST/DELETE,+ * `template/import`) over a REAL socket through the composed `bootServer`+ * stack: verb gating, real handler responses, and the shared admission+ * posture. All three paths are legacy `MUTATING_ROUTES` members — that+ * DECLARATION is pinned at the table tier in+ * `http/folder-template-routes.test.ts`; the rebound-Host pins here hold+ * that the admission outcome is unchanged across the lift, GET arms+ * included.+ *+ * Every request below refuses (or reads) BEFORE any CRDT/session write —+ * the deep template write/move/import behavior keeps its coverage in the+ * dedicated integration suites, which now exercise the same native dispatch.+ */++/** Every path in the group, with the verbs the legacy record dispatched. */+const METHOD_SURFACE: ReadonlyArray<{ path: string; unsupported: string; allow: string }> = [+ { path: '/api/folder-config', unsupported: 'DELETE', allow: 'GET, PUT' },+ { path: '/api/template', unsupported: 'PATCH', allow: 'GET, PUT, POST, DELETE' },+ { path: '/api/template/import', unsupported: 'GET', allow: 'POST' },+];++const ALL_ROUTES = METHOD_SURFACE.map(({ path }) => path);++let tmpRoot: string;+let server: BootedServer;++beforeAll(async () => {+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-folder-template-native-'));+ const contentDir = mkdtempSync(resolve(tmpRoot, 'content-'));+ writeFileSync(resolve(contentDir, 'alpha.md'), '# Alpha\n\nBody.\n', 'utf-8');+ server = await bootCompositionRig(contentDir);+ await server.ready;+}, 60_000);++afterAll(async () => {+ await server?.destroy();+ await rm(tmpRoot, { recursive: true, force: true });+});++describe('folder-template group over the composed listener — served natively', () => {+ test('every path is registered natively with verb gating (405 + Allow)', async () => {+ for (const { path, unsupported, allow } of METHOD_SURFACE) {+ const res = await fetch(`http://127.0.0.1:${server.port}${path}`, { method: unsupported });+ expect(res.status, path).toBe(405);+ expect(res.headers.get('allow'), path).toBe(allow);+ }+ });++ test('GET /api/folder-config serves the project root folder meta natively', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/folder-config?path=`);+ expect(res.status).toBe(200);+ expect(res.headers.get('content-type')).toBe('application/json');+ expect(res.headers.get('x-request-id')).not.toBeNull();+ const body = (await res.json()) as { folder?: unknown };+ expect(body.folder).toBeDefined();+ });++ test('folder-config rejects an escaping path with its own 400 (dispatch reaches the handler)', async () => {+ const res = await fetch(+ `http://127.0.0.1:${server.port}/api/folder-config?path=${encodeURIComponent('../escape')}`,+ );+ expect(res.status).toBe(400);+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-request');+ });++ test('GET /api/template walks leaf → root and 404s an absent template', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/template?name=absent&folder=`);+ expect(res.status).toBe(404);+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:template-not-found');+ });++ test('template name validation survives the lift (bad name → 400)', async () => {+ const res = await fetch(+ `http://127.0.0.1:${server.port}/api/template?name=${encodeURIComponent('bad.name')}&folder=`,+ );+ expect(res.status).toBe(400);+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-request');+ });++ test('template/import refuses a schema-invalid body with 400 before any doc read', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/template/import`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({}),+ });+ expect(res.status).toBe(400);+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-request');+ });++ test('all three paths refuse a rebound Host before the verb check (403, no Allow leak)', async () => {+ for (const path of ALL_ROUTES) {+ // DELETE/PATCH-class wrong verbs above prove 405 from loopback; here the+ // mutating gate must answer first even on a wrong-verb request.+ const res = await rawRequest(server.port, path, { headers: { Host: 'evil.example' } });+ expect(res.status, path).toBe(403);+ expect(res.headers.allow, path).toBeUndefined();+ expect(parseProblem(res.body).type, path).toBe('urn:ok:error:host-not-allowed');+ }+ });++ test('foreign Origin is refused before dispatch on a ported route', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/folder-config?path=`, {+ headers: { Origin: 'https://evil.example' },+ });+ expect(res.status).toBe(403);+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-origin');+ });++ test('sibling native groups still answer on the same server (multi-group dispatch)', async () => {+ const linkGraph = await fetch(`http://127.0.0.1:${server.port}/api/backlinks?docName=alpha`);+ expect(linkGraph.status).toBe(200);+ const packs = await fetch(`http://127.0.0.1:${server.port}/api/seed/packs`);+ expect(packs.status).toBe(200);+ });+});diff --git a/packages/server/src/api-seed-composition.test.ts b/packages/server/src/api-seed-composition.test.tsnew file mode 100644index 000000000..233db5046--- /dev/null+++ b/packages/server/src/api-seed-composition.test.ts@@ -0,0 +1,137 @@+import { mkdtempSync, writeFileSync } from 'node:fs';+import { mkdtemp, rm } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { resolve } from 'node:path';+import { afterAll, beforeAll, describe, expect, test } from 'vitest';+import type { BootedServer } from './boot.ts';+import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.test-helper.ts';++/**+ * Characterization: the natively-routed seed group (`seed/plan`, `seed/packs`+ * reads; `seed/apply`, `seed/install-pack-skill` mutating) over a REAL socket+ * through the composed `bootServer` stack: verb gating, real handler+ * responses, and the shared admission posture. The wire cannot distinguish+ * the mutating gate from the read gate (both apply the same loopback ++ * workspace-Host checks), so the mutating DECLARATION is pinned at the table+ * tier in `http/seed-routes.test.ts`; the rebound-Host pins here hold that+ * the admission outcome is unchanged across the lift.+ *+ * The rig seeds `<contentDir>/.ok/config.yml`, so `seed/plan` runs past its+ * prerequisite check and serves a real plan; no request below writes to disk+ * (`apply` refuses before `applySeed` on the malformed-plan pin).+ */++/** Every path in the group, with the verbs the legacy record dispatched. */+const METHOD_SURFACE: ReadonlyArray<{ path: string; unsupported: string; allow: string }> = [+ { path: '/api/seed/plan', unsupported: 'POST', allow: 'GET' },+ { path: '/api/seed/packs', unsupported: 'POST', allow: 'GET' },+ { path: '/api/seed/apply', unsupported: 'GET', allow: 'POST' },+ { path: '/api/seed/install-pack-skill', unsupported: 'GET', allow: 'POST' },+];++/** Legacy `MUTATING_ROUTES` members (declaration pinned in the table suite). */+const MUTATING_ROUTES = ['/api/seed/apply', '/api/seed/install-pack-skill'];++let tmpRoot: string;+let server: BootedServer;++beforeAll(async () => {+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-seed-native-'));+ const contentDir = mkdtempSync(resolve(tmpRoot, 'content-'));+ writeFileSync(resolve(contentDir, 'alpha.md'), '# Alpha\n\nBody.\n', 'utf-8');+ server = await bootCompositionRig(contentDir);+ await server.ready;+}, 60_000);++afterAll(async () => {+ await server?.destroy();+ await rm(tmpRoot, { recursive: true, force: true });+});++describe('seed group over the composed listener — served natively', () => {+ test('every path is registered natively with verb gating (405 + Allow)', async () => {+ for (const { path, unsupported, allow } of METHOD_SURFACE) {+ const res = await fetch(`http://127.0.0.1:${server.port}${path}`, { method: unsupported });+ expect(res.status, path).toBe(405);+ expect(res.headers.get('allow'), path).toBe(allow);+ }+ });++ test('GET /api/seed/packs serves the starter-pack registry natively', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/seed/packs`);+ expect(res.status).toBe(200);+ expect(res.headers.get('content-type')).toBe('application/json');+ expect(res.headers.get('x-request-id')).not.toBeNull();+ const body = (await res.json()) as { packs?: unknown[] };+ expect(Array.isArray(body.packs)).toBe(true);+ expect(body.packs?.length).toBeGreaterThan(0);+ });++ test('GET /api/seed/plan serves a real plan (rig seeds the config.yml prerequisite)', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/seed/plan`);+ expect(res.status).toBe(200);+ const body = (await res.json()) as { plan?: unknown };+ expect(body.plan).toBeDefined();+ });++ test('unknown packId reaches the real handlers (their own 400, not a route-miss 404)', async () => {+ const viaPlan = await fetch(+ `http://127.0.0.1:${server.port}/api/seed/plan?packId=not-a-real-pack`,+ );+ expect(viaPlan.status).toBe(400);+ expect(((await viaPlan.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-request');++ const viaInstall = await fetch(`http://127.0.0.1:${server.port}/api/seed/install-pack-skill`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ packId: 'not-a-real-pack' }),+ });+ expect(viaInstall.status).toBe(400);+ expect(((await viaInstall.json()) as { type?: string }).type).toBe(+ 'urn:ok:error:invalid-request',+ );+ });++ test('POST /api/seed/apply refuses a malformed plan with its own 400 (no disk write)', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/seed/apply`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ plan: 'not-an-object' }),+ });+ expect(res.status).toBe(400);+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-request');+ });++ test('mutating pair refuses a rebound Host before the verb check (403, no Allow leak)', async () => {+ for (const path of MUTATING_ROUTES) {+ // GET is the wrong verb for both — the mutating gate must answer first.+ const res = await rawRequest(server.port, path, { headers: { Host: 'evil.example' } });+ expect(res.status, path).toBe(403);+ expect(res.headers.allow, path).toBeUndefined();+ expect(parseProblem(res.body).type, path).toBe('urn:ok:error:host-not-allowed');+ }+ });++ test('read pair is Host-gated by the shared read choke point', async () => {+ for (const path of ['/api/seed/plan', '/api/seed/packs']) {+ const res = await rawRequest(server.port, path, { headers: { Host: 'evil.example' } });+ expect(res.status, path).toBe(403);+ expect(parseProblem(res.body).type, path).toBe('urn:ok:error:host-not-allowed');+ }+ });++ test('foreign Origin is refused before dispatch on a ported route', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/seed/packs`, {+ headers: { Origin: 'https://evil.example' },+ });+ expect(res.status).toBe(403);+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-origin');+ });++ test('sibling native groups still answer on the same server (multi-group dispatch)', async () => {+ const linkGraph = await fetch(`http://127.0.0.1:${server.port}/api/backlinks?docName=alpha`);+ expect(linkGraph.status).toBe(200);+ const packs = await fetch(`http://127.0.0.1:${server.port}/api/seed/packs`);+ expect(packs.status).toBe(200);+ });+});diff --git a/packages/server/src/api-system-actions-composition.test.ts b/packages/server/src/api-system-actions-composition.test.tsnew file mode 100644index 000000000..47ca78058--- /dev/null+++ b/packages/server/src/api-system-actions-composition.test.ts@@ -0,0 +1,119 @@+import { mkdtempSync, writeFileSync } from 'node:fs';+import { mkdtemp, rm } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { resolve } from 'node:path';+import { afterAll, beforeAll, describe, expect, test } from 'vitest';+import type { BootedServer } from './boot.ts';+import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.test-helper.ts';++/**+ * Characterization: the natively-routed system-actions group (`spawn-cursor`,+ * `handoff`, `client-logs`) over a REAL socket through the composed+ * `bootServer` stack: verb gating, real handler refusals, and the shared+ * admission posture. `spawn-cursor` and `handoff` stay OFF the table's+ * mutating declaration (their loopback confinement is the in-handler+ * `checkLocalOpSecurity` first line — pinned at the table tier in+ * `http/system-actions-routes.test.ts`); the rebound-Host pins here hold+ * that the admission outcome is unchanged across the lift.+ *+ * Every request below refuses (or, for `client-logs`, ingests an empty+ * batch) BEFORE any editor-host side effect — the suite never spawns a+ * binary or dispatches a handoff URL.+ */++let tmpRoot: string;+let server: BootedServer;++beforeAll(async () => {+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-system-actions-native-'));+ const contentDir = mkdtempSync(resolve(tmpRoot, 'content-'));+ writeFileSync(resolve(contentDir, 'alpha.md'), '# Alpha\n\nBody.\n', 'utf-8');+ server = await bootCompositionRig(contentDir);+ await server.ready;+}, 60_000);++afterAll(async () => {+ await server?.destroy();+ await rm(tmpRoot, { recursive: true, force: true });+});++describe('system-actions group over the composed listener — served natively', () => {+ test('every path is registered natively with verb gating (405 + Allow: POST)', async () => {+ for (const path of ['/api/spawn-cursor', '/api/handoff', '/api/client-logs']) {+ const res = await fetch(`http://127.0.0.1:${server.port}${path}`);+ expect(res.status, path).toBe(405);+ expect(res.headers.get('allow'), path).toBe('POST');+ }+ });++ test('spawn-cursor reaches the real handler (its own 400 before any spawn)', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/spawn-cursor`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({}),+ });+ expect(res.status).toBe(400);+ const body = (await res.json()) as { type?: string; title?: string };+ expect(body.type).toBe('urn:ok:error:invalid-request');+ expect(body.title).toContain('path');+ expect(res.headers.get('x-request-id')).not.toBeNull();+ });++ test('handoff reaches the real handler (schema 400 before any dispatch)', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/handoff`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({}),+ });+ expect(res.status).toBe(400);+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-request');+ });++ test('client-logs ingests a batch natively (accepted count, gap marker tolerated)', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/client-logs`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({+ entries: [{ level: 'info', message: 'composition-pin entry' }],+ droppedSinceLastFlush: 1,+ }),+ });+ expect(res.status).toBe(200);+ expect(((await res.json()) as { accepted?: number }).accepted).toBe(1);+ });++ test('client-logs refuses a rebound Host before the verb check (403, no Allow leak)', async () => {+ // GET is the wrong verb — the mutating gate must answer first.+ const res = await rawRequest(server.port, '/api/client-logs', {+ headers: { Host: 'evil.example' },+ });+ expect(res.status).toBe(403);+ expect(res.headers.allow).toBeUndefined();+ expect(parseProblem(res.body).type).toBe('urn:ok:error:host-not-allowed');+ });++ test('spawn-cursor and handoff are Host-gated by the shared read choke point', async () => {+ for (const path of ['/api/spawn-cursor', '/api/handoff']) {+ const res = await rawRequest(server.port, path, { headers: { Host: 'evil.example' } });+ expect(res.status, path).toBe(403);+ expect(parseProblem(res.body).type, path).toBe('urn:ok:error:host-not-allowed');+ }+ });++ test('foreign Origin is refused before dispatch on a ported route', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/client-logs`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json', Origin: 'https://evil.example' },+ body: JSON.stringify({ entries: [] }),+ });+ expect(res.status).toBe(403);+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-origin');+ });++ test('sibling native groups still answer on the same server (multi-group dispatch)', async () => {+ const linkGraph = await fetch(`http://127.0.0.1:${server.port}/api/backlinks?docName=alpha`);+ expect(linkGraph.status).toBe(200);+ const packs = await fetch(`http://127.0.0.1:${server.port}/api/seed/packs`);+ expect(packs.status).toBe(200);+ });+});diff --git a/packages/server/src/http/folder-template-routes.test.ts b/packages/server/src/http/folder-template-routes.test.tsnew file mode 100644index 000000000..1ac8494f8--- /dev/null+++ b/packages/server/src/http/folder-template-routes.test.ts@@ -0,0 +1,70 @@+import type { Hocuspocus } from '@hocuspocus/server';+import { describe, expect, test } from 'vitest';+import type { AgentSessionManager } from '../agent-sessions.ts';+import { loggerFactory } from '../logger.ts';+import { createFolderTemplateRoutes } from './folder-template-routes.ts';++/**+ * Table-level pins for the folder-template group's mutating declaration. The+ * wire cannot pin this: the read half of the DNS-rebinding defense applies+ * the identical loopback + workspace-Host checks to every `/api/*` request,+ * so an emptied mutating set changes no composition-suite response — only+ * which gate (and telemetry tag) fires first. The declared membership is+ * pinned here directly against the legacy `MUTATING_ROUTES` membership it+ * reproduces — all three paths were members (any-verb-mutates ⇒ every verb,+ * GET arms included).+ */++function buildGroup() {+ return createFolderTemplateRoutes({+ contentDir: '/nonexistent-content',+ projectDir: undefined,+ ephemeral: true,+ log: loggerFactory.getLogger('test'),+ // Never dispatched by these pins; the table declaration is what's under test.+ hocuspocus: {} as Hocuspocus,+ sessionManager: {} as AgentSessionManager,+ getPrincipal: undefined,+ signalChannel: undefined,+ getSyncEngine: undefined,+ recentlyRemovedDocs: undefined,+ isSafeDocName: () => false,+ resolveAlias: (docName) => docName,+ resolveContentEntryPath: () => '/nonexistent-content/none',+ validateFolderRel: () => null,+ extractAgentIdentity: () => ({+ agentId: 'test',+ agentName: 'test',+ colorSeed: 'test',+ clientName: undefined,+ }),+ extractActorIdentityFromQuery: () => ({ kind: 'invalid-summary' as const }),+ okArtifactKey: () => '',+ attributeOkArtifactWrite: () => {},+ scheduleOkArtifactFlush: () => {},+ flushDiskAndDetectOutcome: () => Promise.resolve(null),+ respondPersistenceFailure: () => {},+ respondDiskDivergence: () => {},+ registerWrittenDocInFileIndex: () => {},+ captureAndCloseDocuments: () => Promise.resolve(new Map()),+ renameTrackedPathInGit: () => Promise.resolve(false),+ renamePathOnDisk: () => {},+ splitContentPath: (path) => ({ parent: '', basename: path }),+ mutateFileIndex: undefined,+ });+}++describe('createFolderTemplateRoutes table', () => {+ test('registers exactly the three folder-template paths', () => {+ expect([...buildGroup().paths].sort()).toEqual(+ ['/api/folder-config', '/api/template', '/api/template/import'].sort(),+ );+ });++ test('every path reproduces its legacy MUTATING_ROUTES membership (all three mutating)', () => {+ const { table } = buildGroup();+ for (const path of ['/api/folder-config', '/api/template', '/api/template/import']) {+ expect(table.isMutating(path), path).toBe(true);+ }+ });+});diff --git a/packages/server/src/http/folder-template-routes.ts b/packages/server/src/http/folder-template-routes.tsnew file mode 100644index 000000000..d332151e1--- /dev/null+++ b/packages/server/src/http/folder-template-routes.ts@@ -0,0 +1,1217 @@+/**+ * The folder-artifact family — `folder-config` (GET+PUT) plus the template+ * CRUD surface `template` (GET/PUT/POST/DELETE) and `template/import` —+ * natively routed as one group. Both families write `<folder>/.ok/*`+ * artifacts through the shared actor-attribution spine+ * (`attributeOkArtifactWrite` / `okArtifactKey` / `scheduleOkArtifactFlush`),+ * which is why they lift together. What the handlers reach for arrives as+ * {@link FolderTemplateRouteDeps}.+ *+ * All three paths are legacy `MUTATING_ROUTES` members (any-verb-mutates ⇒+ * every verb rides the mutating gate, GET arms included) — `mutating` below+ * reproduces that membership exactly.+ *+ * Templates are real CRDT content docs (`<folder>/.ok/templates/<name>`), so+ * the write handlers run the same conflict gate + paired-write + flush+ * machinery as the sibling content-write handlers; those spines stay in the+ * extension and arrive as deps.+ */++import { existsSync, readFileSync } from 'node:fs';+import { readFile } from 'node:fs/promises';+import type { ServerResponse } from 'node:http';+import { relative, resolve, sep } from 'node:path';+import type { Hocuspocus } from '@hocuspocus/server';+import {+ EmptyRequestSchema,+ FolderConfigGetSuccessSchema,+ FolderConfigPutRequestSchema,+ FolderConfigPutSuccessSchema,+ instantiateDoc,+ type Principal,+ parseTemplateFile,+ stripFrontmatter,+ TEMPLATE_NAME_REGEX,+ TemplateDeleteSuccessSchema,+ TemplateGetSuccessSchema,+ TemplateImportRequestSchema,+ TemplateImportSuccessSchema,+ TemplateMoveRequestSchema,+ TemplateMoveSuccessSchema,+ TemplatePutRequestSchema,+ TemplatePutSuccessSchema,+ templateContentDocName,+ unwrapFrontmatterFences,+} from '@inkeep/open-knowledge-core';+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';+import type { AgentSessionManager } from '../agent-sessions.ts';+import { composeAndWriteRawBody } from '../bridge-intake.ts';+import { isConfigDoc, isSystemDoc } from '../cc1-broadcast.ts';+import { DocInConflictError, isDocInConflict, respondDocInConflict } from '../conflict-errors.ts';+import { enrichDirectory } from '../content/enrichment.ts';+import { applyFolderFrontmatterPatch } from '../content/folder-frontmatter-write.ts';+import {+ applyTemplateDelete,+ applyTemplateMove,+ applyTemplateWrite,+ composeTemplateContent,+ type TemplateFrontmatter,+} from '../content/templates-write.ts';+import type { StoreFailure } from '../document-durability-state.ts';+import { extractActorIdentity } from '../extract-actor-identity.ts';+import type { DiskEvent } from '../file-watcher.ts';+import { tracedUnlinkSync } from '../fs-traced.ts';+import type { PinoLogger } from '../logger.ts';+import { extractPageTitle } from '../page-identity.ts';+import type { RecentlyRemovedDocs } from '../recently-removed-docs.ts';+import type { SyncEngine } from '../sync-engine.ts';+import { type ApiRouteGroup, createApiRouteGroup } from './api-pipeline.ts';+import { errorResponse } from './error-response.ts';+import { methodRouter } from './method-router.ts';+import { withValidation } from './request-validation.ts';+import { successResponse } from './success-response.ts';++export interface FolderTemplateRouteDeps {+ contentDir: string;+ projectDir: string | undefined;+ ephemeral: boolean;+ log: PinoLogger;+ hocuspocus: Hocuspocus;+ sessionManager: AgentSessionManager;+ getPrincipal: (() => Principal | null) | undefined;+ signalChannel: ((channel: 'files' | 'lint-config' | 'comments') => void) | undefined;+ getSyncEngine: (() => SyncEngine | null) | undefined;+ recentlyRemovedDocs: RecentlyRemovedDocs | undefined;+ isSafeDocName: (docName: string) => boolean;+ resolveAlias: (docName: string) => string;+ resolveContentEntryPath: (contentDir: string, kind: 'file' | 'folder', path: string) => string;+ /** The extension's shared folder-path validator (also a history-group dep). */+ validateFolderRel: (+ raw: string,+ res: ServerResponse,+ label?: 'path' | 'folder',+ handler?: string,+ ) => { folderRel: string; resolvedContentDir: string } | null;+ /** Narrowed to the identity fields the template session open consumes. */+ extractAgentIdentity: (body: Record<string, unknown>) => {+ agentId: string;+ agentName: string;+ colorSeed: string;+ clientName: string | undefined;+ };+ extractActorIdentityFromQuery: (+ url: URL,+ principal: (() => Principal | null) | undefined,+ ) => ReturnType<typeof extractActorIdentity>;+ okArtifactKey: (+ kind: 'template' | 'folder-frontmatter' | 'folder' | 'skill',+ folder: string,+ name?: string,+ ) => string;+ attributeOkArtifactWrite: (+ actor: ReturnType<typeof extractActorIdentity>,+ artifactKey: string,+ subject: string,+ previousPaths?: Array<{ from: string; to: string }>,+ ) => void;+ scheduleOkArtifactFlush: (context: string) => void;+ flushDiskAndDetectOutcome: (+ docName: string,+ ) => Promise<{ kind: 'failure'; failure: StoreFailure } | { kind: 'divergence' } | null>;+ respondPersistenceFailure: (res: ServerResponse, failure: StoreFailure, handler: string) => void;+ respondDiskDivergence: (res: ServerResponse, handler: string) => void;+ registerWrittenDocInFileIndex: (docName: string, content: string) => void;+ captureAndCloseDocuments: (+ docNames: string[],+ lifecycleStatus: 'deleted-upstream' | 'renamed',+ ) => Promise<Map<string, string>>;+ renameTrackedPathInGit: (+ projectDir: string | undefined,+ sourcePath: string,+ destinationPath: string,+ ) => Promise<boolean>;+ renamePathOnDisk: (sourcePath: string, destinationPath: string) => void;+ /** Shared content-path splitter (module helper in the extension). */+ splitContentPath: (path: string) => { parent: string; basename: string };+ /** Post-write file-index mutator (absent when the watcher owns the index). */+ mutateFileIndex: ((event: DiskEvent) => void) | undefined;+}++export function createFolderTemplateRoutes(deps: FolderTemplateRouteDeps): ApiRouteGroup {+ const {+ contentDir,+ projectDir,+ ephemeral,+ log,+ hocuspocus,+ sessionManager,+ getPrincipal,+ signalChannel,+ getSyncEngine,+ recentlyRemovedDocs,+ isSafeDocName,+ resolveAlias,+ resolveContentEntryPath,+ validateFolderRel,+ extractAgentIdentity,+ extractActorIdentityFromQuery,+ okArtifactKey,+ attributeOkArtifactWrite,+ scheduleOkArtifactFlush,+ flushDiskAndDetectOutcome,+ respondPersistenceFailure,+ respondDiskDivergence,+ registerWrittenDocInFileIndex,+ captureAndCloseDocuments,+ renameTrackedPathInGit,+ renamePathOnDisk,+ splitContentPath,+ mutateFileIndex,+ } = deps;++ function validateTemplateName(name: string, res: ServerResponse, handler = 'template'): boolean {+ if (!name || !TEMPLATE_NAME_REGEX.test(name)) {+ errorResponse(+ res,+ 400,+ 'urn:ok:error:invalid-request',+ 'Invalid name: must be letters / digits / `_` / `-` only (no `.md` extension).',+ { handler },+ );+ return false;+ }+ return true;+ }++ /**+ * Resolve a template by walking leaf → root from `folderRel`, closest-wins.+ * Returns the matched file's abs path, the owning folder, and whether it's+ * `local` (owned by `folderRel` itself) or `inherited` (from an ancestor).+ * Single source of the resolution walk — shared by `handleTemplateGet` and+ * the move handler's inherited-vs-absent disambiguation.+ */+ function findTemplateLeafToRoot(+ resolvedContentDir: string,+ folderRel: string,+ name: string,+ ): { abs: string; folder: string; scope: 'local' | 'inherited' } | null {+ const segments = folderRel === '' ? [] : folderRel.split('/');+ for (let depth = segments.length; depth >= 0; depth--) {+ const ancestorFolder = depth === 0 ? '' : segments.slice(0, depth).join('/');+ const ancestorAbs =+ ancestorFolder === '' ? resolvedContentDir : resolve(resolvedContentDir, ancestorFolder);+ if (+ ancestorAbs !== resolvedContentDir &&+ !ancestorAbs.startsWith(`${resolvedContentDir}${sep}`)+ ) {+ continue;+ }+ const candidate = resolve(ancestorAbs, '.ok', 'templates', `${name}.md`);+ if (existsSync(candidate)) {+ return {+ abs: candidate,+ folder: ancestorFolder,+ scope: depth === segments.length ? 'local' : 'inherited',+ };+ }+ }+ return null;+ }++ function pickFrontmatterFields(raw: unknown): Record<string, unknown> {+ const out: Record<string, unknown> = {};+ if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return out;+ for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {+ if (value === undefined) continue;+ out[key] = value;+ }+ return out;+ }++ /**+ * The CRDT doc name a template opens/persists under — its content-relative path+ * (`<folderRel>/.ok/templates/<name>`, ext-less, RAW). Delegates to the core+ * builder so server handlers, the client open path, and the properties panel+ * share one identity. `''` folder → `.ok/templates/<name>` (project root).+ */+ function templateDocNameFor(folderRel: string, name: string): string {+ return templateContentDocName(folderRel, name);+ }++ const handleFolderConfigGet = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ try {+ const url = new URL(req.url ?? '', 'http://localhost');+ const validated = validateFolderRel(+ url.searchParams.get('path') ?? '',+ res,+ 'path',+ 'folder-config-get',+ );+ if (!validated) return;+ const meta = await enrichDirectory(validated.folderRel, {+ projectDir: validated.resolvedContentDir,+ });+ const folderOkDir = resolve(validated.resolvedContentDir, validated.folderRel, '.ok');+ const localFmPath = resolve(folderOkDir, 'frontmatter.yml');+ let frontmatterLocal: Record<string, unknown> | null = null;+ if (existsSync(localFmPath)) {+ try {+ const raw = await readFile(localFmPath, 'utf-8');+ const parsed = parseYaml(raw);+ if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {+ frontmatterLocal = parsed as Record<string, unknown>;+ } else {+ frontmatterLocal = {};+ }+ } catch (err) {+ const reason = err instanceof Error ? err.message : String(err);+ log.warn(+ { path: localFmPath, reason },+ `[folder-config:get] malformed YAML in ${localFmPath}: ${reason}`,+ );+ frontmatterLocal = null;+ }+ }++ // Folder frontmatter is SELF-ONLY (no ancestor cascade) and there+ // are no schema declarations — `frontmatter_local` is the folder's+ // own open-shape frontmatter, the whole contract.+ successResponse(+ res,+ 200,+ FolderConfigGetSuccessSchema,+ {+ folder: meta,+ frontmatter_local: frontmatterLocal,+ },+ { handler: 'folder-config-get' },+ );+ } catch (e) {+ errorResponse(+ res,+ 500,+ 'urn:ok:error:internal-server-error',+ 'Failed to read folder config.',+ { handler: 'folder-config-get', cause: e },+ );+ }+ },+ { handler: 'folder-config-get', method: 'GET', skipBodyParse: true },+ );++ const handleFolderConfigPut = withValidation(+ FolderConfigPutRequestSchema,+ async (_req, res, body) => {+ try {+ // No-project single-file mode writes nothing into the user's directory+ // beyond the one edited doc. Folder config would land a+ // `<folder>/.ok/frontmatter.yml` sidecar in the user's tree — refuse.+ if (ephemeral) {+ errorResponse(+ res,+ 403,+ 'urn:ok:error:single-file-mode',+ 'Folder configuration is not available in single-file mode.',+ { handler: 'folder-config-put' },+ );+ return;+ }+ const actor = extractActorIdentity(+ body as unknown as Record<string, unknown>,+ getPrincipal,+ );+ if (actor.kind === 'invalid-summary') {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {+ handler: 'folder-config-put',+ });+ return;+ }+ const validated = validateFolderRel(body.path, res, 'path', 'folder-config-put');+ if (!validated) return;++ // Write the folder's own frontmatter (open-shape, like a doc's) via the+ // single-folder merge-patch helper — addressed by the folder's own+ // path, no glob and no whitelist.+ const allApplied: Array<{ path: string; action: 'written' | 'deleted' | 'noop' }> = [];+ if (body.frontmatter !== undefined) {+ const result = applyFolderFrontmatterPatch({+ anchorDir: validated.resolvedContentDir,+ folderRel: validated.folderRel,+ patch: body.frontmatter,+ });+ if (!result.ok) {+ const status = result.error.code === 'WRITE_ERROR' ? 500 : 400;+ const urn =+ status === 500+ ? 'urn:ok:error:internal-server-error'+ : 'urn:ok:error:invalid-request';+ const title = status === 500 ? 'Failed to write folder config.' : result.error.message;+ errorResponse(res, status, urn, title, {+ handler: 'folder-config-put',+ detail: result.error.code,+ cause: new Error(result.error.message),+ });+ return;+ }+ allApplied.push({ path: result.path, action: result.action });+ // Attribute the frontmatter change (skip a no-op patch).+ if (result.action !== 'noop') {+ attributeOkArtifactWrite(+ actor,+ okArtifactKey('folder-frontmatter', validated.folderRel),+ `folder-frontmatter-${result.action === 'deleted' ? 'delete' : 'edit'}: ${result.path}`,+ );+ scheduleOkArtifactFlush('folder-config-put');+ }+ }++ successResponse(+ res,+ 200,+ FolderConfigPutSuccessSchema,+ { applied: allApplied },+ { handler: 'folder-config-put' },+ );+ } catch (e) {+ errorResponse(+ res,+ 500,+ 'urn:ok:error:internal-server-error',+ 'Failed to write folder config.',+ { handler: 'folder-config-put', cause: e },+ );+ }+ },+ { handler: 'folder-config-put', method: 'PUT' },+ );++ const handleFolderConfig = methodRouter(+ { GET: handleFolderConfigGet, PUT: handleFolderConfigPut },+ { handler: 'folder-config' },+ );++ /**+ * Conflict-aware refusal helper for the template handlers. A template is a+ * content doc now (`<folder>/.ok/templates/<name>`), so its live Y.Doc carries+ * a `lifecycle.status` Y.Map — a mutation against one mid-conflict must refuse+ * exactly like the sibling content-write handlers, whose paired-write path+ * (`composeAndWriteRawBody`) would otherwise clobber a doc the user is+ * mid-resolving. Takes the pre-resolved content doc name — same shape as the+ * sibling `checkSkillDocConflictGate`, so the two gates read as one pattern.+ * Returns `true` when the gate fired (caller short-circuits); `false` when+ * the mutation may proceed.+ */+ function checkTemplateConflictGate(+ templateDocName: string,+ handler: 'template-put' | 'template-delete' | 'template-move' | 'template-import',+ res: ServerResponse,+ ): boolean {+ const doc = hocuspocus.documents.get(templateDocName);+ if (doc && isDocInConflict(doc)) {+ respondDocInConflict(res, new DocInConflictError({ file: `${templateDocName}.md` }), handler);+ return true;+ }+ return false;+ }++ const handleTemplateGet = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ try {+ const url = new URL(req.url ?? '', 'http://localhost');+ const name = url.searchParams.get('name') ?? '';+ if (!validateTemplateName(name, res, 'template-get')) return;++ // Walk leaf → root for closest match.+ const validated = validateFolderRel(+ url.searchParams.get('folder') ?? '',+ res,+ 'folder',+ 'template-get',+ );+ if (!validated) return;+ const { folderRel, resolvedContentDir } = validated;++ const found = findTemplateLeafToRoot(resolvedContentDir, folderRel, name);+ if (!found) {+ errorResponse(res, 404, 'urn:ok:error:template-not-found', 'Template not found.', {+ handler: 'template-get',+ detail: `Template "${name}" not found for folder "${folderRel || '.'}". Walked leaf → root.`,+ });+ return;+ }+ const { abs: foundAbs, folder: foundFolder, scope: foundScope } = found;++ const raw = await readFile(foundAbs, 'utf-8');+ // Normalize single-block (and legacy two-block) templates: wire+ // `frontmatter` = the template's identity (title/description), wire+ // `body` = the starter content (doc-frontmatter block + markdown) a+ // new doc receives. Tokens (`{{date}}`) are preserved verbatim.+ const model = parseTemplateFile(raw);+ const frontmatter = model.identity as Record<string, unknown>;+ const body = model.starterContent;++ const relPath = relative(resolvedContentDir, foundAbs)+ .split(/[\\/]/)+ .filter(Boolean)+ .join('/');++ successResponse(+ res,+ 200,+ TemplateGetSuccessSchema,+ {+ template: {+ name,+ folder: foundFolder,+ scope: foundScope,+ path: relPath,+ frontmatter,+ body,+ },+ },+ { handler: 'template-get' },+ );+ } catch (e) {+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to read template.', {+ handler: 'template-get',+ cause: e,+ });+ }+ },+ { handler: 'template-get', method: 'GET', skipBodyParse: true },+ );++ const handleTemplatePut = withValidation(+ TemplatePutRequestSchema,+ async (_req, res, body) => {+ try {+ // Templates write `<folder>/.ok/templates/*.md` into the content tree —+ // a user-dir artifact single-file mode must never create.+ if (ephemeral) {+ errorResponse(+ res,+ 403,+ 'urn:ok:error:single-file-mode',+ 'Templates are not available in single-file mode.',+ { handler: 'template-put' },+ );+ return;+ }+ const actor = extractActorIdentity(+ body as unknown as Record<string, unknown>,+ getPrincipal,+ );+ if (actor.kind === 'invalid-summary') {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {+ handler: 'template-put',+ });+ return;+ }+ const name = body.name;+ if (!validateTemplateName(name, res, 'template-put')) return;+ const validated = validateFolderRel(body.folder, res, 'folder', 'template-put');+ if (!validated) return;++ // Conflict-aware refusal. See `checkTemplateConflictGate`.+ if (+ checkTemplateConflictGate(+ templateDocNameFor(validated.folderRel, name),+ 'template-put',+ res,+ )+ )+ return;++ // Compose + validate the `.md` bytes server-side, then route the body+ // through the template's CRDT doc (precedent #24 / #38) — same shape as+ // skill-put. Templates are content docs, so the ordinary content+ // persistence path (not the managed-artifact branch) writes the file.+ const composed = composeTemplateContent({+ name,+ body: typeof body.body === 'string' ? body.body : '',+ frontmatter: pickFrontmatterFields(body.frontmatter) satisfies TemplateFrontmatter,+ });+ if (!composed.ok) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid template request.', {+ handler: 'template-put',+ detail: composed.error.code,+ cause: new Error(composed.error.message),+ });+ return;+ }++ const templateFilePath = resolve(+ validated.resolvedContentDir,+ validated.folderRel,+ '.ok',+ 'templates',+ `${name}.md`,+ );+ const templateCreated = !existsSync(templateFilePath);+ const templateRelPath = relative(validated.resolvedContentDir, templateFilePath)+ .split(/[\\/]/)+ .filter(Boolean)+ .join('/');+ const templateDocName = templateDocNameFor(validated.folderRel, name);++ const { agentId, agentName, colorSeed, clientName } = extractAgentIdentity(+ body as unknown as Record<string, unknown>,+ );+ const templateSession = await sessionManager.getSession(templateDocName, agentId, {+ displayName: agentName,+ colorSeed,+ clientName,+ });+ templateSession.dc.document.transact(() => {+ composeAndWriteRawBody(templateSession.dc.document, composed.content, 'agent');+ }, templateSession.origin);++ const templateFlush = await flushDiskAndDetectOutcome(templateDocName);+ if (templateFlush?.kind === 'failure') {+ respondPersistenceFailure(res, templateFlush.failure, 'template-put');+ return;+ }+ if (templateFlush?.kind === 'divergence') {+ respondDiskDivergence(res, 'template-put');+ return;+ }++ // Close the dropped-FSEvent gap at the source (see helper): the flush+ // may have just created this folder's `.ok/templates/` dir — exactly+ // the brand-new-subdir race where the watcher's create event can be+ // lost. Same net as the sibling agent-write handlers.+ registerWrittenDocInFileIndex(templateDocName, composed.content);++ attributeOkArtifactWrite(+ actor,+ okArtifactKey('template', validated.folderRel, name),+ `${templateCreated ? 'template-create' : 'template-edit'}: ${templateRelPath}`,+ );+ scheduleOkArtifactFlush('template-put');+ successResponse(+ res,+ 200,+ TemplatePutSuccessSchema,+ {+ path: templateRelPath,+ created: templateCreated,+ warnings: composed.warnings,+ },+ { handler: 'template-put' },+ );+ } catch (e) {+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to write template.', {+ handler: 'template-put',+ cause: e,+ });+ }+ },+ { handler: 'template-put', method: 'PUT' },+ );++ const handleTemplateDelete = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ try {+ const url = new URL(req.url ?? '', 'http://localhost');+ const name = url.searchParams.get('name') ?? '';+ if (!validateTemplateName(name, res, 'template-delete')) return;+ const validated = validateFolderRel(+ url.searchParams.get('folder') ?? '',+ res,+ 'folder',+ 'template-delete',+ );+ if (!validated) return;++ // DELETE has no body (query-param transport); read identity + summary+ // from the query string into a synthetic body for extractActorIdentity.+ const actor = extractActorIdentityFromQuery(url, getPrincipal);+ if (actor.kind === 'invalid-summary') {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {+ handler: 'template-delete',+ });+ return;+ }++ // Conflict-aware refusal. See `checkTemplateConflictGate`.+ if (+ checkTemplateConflictGate(+ templateDocNameFor(validated.folderRel, name),+ 'template-delete',+ res,+ )+ )+ return;++ // Tear down the live template content doc (if open) BEFORE removing the+ // file, so its debounced content store can't re-store (resurrect) it on+ // a later unload. Same spine doc-delete + skill-delete use; no-op when+ // the doc was never opened.+ await captureAndCloseDocuments(+ [templateDocNameFor(validated.folderRel, name)],+ 'deleted-upstream',+ );++ const deleteInput: Parameters<typeof applyTemplateDelete>[0] = {+ projectDir: validated.resolvedContentDir,+ folder: validated.folderRel,+ name,+ };+ const result = applyTemplateDelete(deleteInput);+ if (!result.ok) {+ const status =+ result.error.code === 'WRITE_ERROR' ||+ result.error.code === 'UNLINK_FAILED' ||+ result.error.code === 'BAD_PROJECT_DIR'+ ? 500+ : 400;+ const urn =+ status === 500 ? 'urn:ok:error:internal-server-error' : 'urn:ok:error:invalid-request';+ const title = status === 500 ? 'Failed to delete template.' : 'Invalid template request.';+ errorResponse(res, status, urn, title, {+ handler: 'template-delete',+ detail: result.error.code,+ cause: new Error(result.error.message),+ });+ return;+ }+ // Only attribute when a file was actually removed (no-op delete of an+ // absent template records nothing).+ if (result.existed) {+ attributeOkArtifactWrite(+ actor,+ okArtifactKey('template', validated.folderRel, name),+ `template-delete: ${result.path}`,+ );+ scheduleOkArtifactFlush('template-delete');+ // Mark the content doc removed so a stale tab redirects instead of+ // offering to resurrect it (parity with ordinary doc deletion).+ recentlyRemovedDocs?.setDeleted(templateDocNameFor(validated.folderRel, name));+ }+ successResponse(+ res,+ 200,+ TemplateDeleteSuccessSchema,+ { existed: result.existed, path: result.path },+ { handler: 'template-delete' },+ );+ } catch (e) {+ errorResponse(+ res,+ 500,+ 'urn:ok:error:internal-server-error',+ 'Failed to delete template.',+ { handler: 'template-delete', cause: e },+ );+ }+ },+ { handler: 'template-delete', method: 'DELETE', skipBodyParse: true },+ );++ const handleTemplateMove = withValidation(+ TemplateMoveRequestSchema,+ async (_req, res, body) => {+ try {+ const actor = extractActorIdentity(+ body as unknown as Record<string, unknown>,+ getPrincipal,+ );+ if (actor.kind === 'invalid-summary') {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {+ handler: 'template-move',+ });+ return;+ }+ if (!validateTemplateName(body.fromName, res, 'template-move')) return;+ if (!validateTemplateName(body.toName, res, 'template-move')) return;+ const fromValidated = validateFolderRel(body.fromFolder, res, 'folder', 'template-move');+ if (!fromValidated) return;+ const toValidated = validateFolderRel(body.toFolder, res, 'folder', 'template-move');+ if (!toValidated) return;++ // Refuse moving a source whose target doc is in an unresolved conflict.+ if (+ checkTemplateConflictGate(+ templateDocNameFor(fromValidated.folderRel, body.fromName),+ 'template-move',+ res,+ )+ ) {+ return;+ }++ // Tear down the live source template content doc (if open) BEFORE the+ // git-mv relocates the file — otherwise its debounced content store+ // would re-store at the now-stale from-path, resurrecting the moved+ // template.+ await captureAndCloseDocuments(+ [templateDocNameFor(fromValidated.folderRel, body.fromName)],+ 'renamed',+ );++ const result = await applyTemplateMove({+ projectDir: fromValidated.resolvedContentDir,+ fromFolder: fromValidated.folderRel,+ fromName: body.fromName,+ toFolder: toValidated.folderRel,+ toName: body.toName,+ // git mv (history-preserving) when the path is tracked; plain disk+ // rename otherwise. `withParentLock` inside renameTrackedPathInGit+ // serializes against concurrent doc renames (git-index safety).+ relocate: async (fromAbs, toAbs) => {+ const movedWithGit = await renameTrackedPathInGit(projectDir, fromAbs, toAbs);+ if (!movedWithGit) renamePathOnDisk(fromAbs, toAbs);+ return movedWithGit;+ },+ });++ if (!result.ok) {+ if (result.error.code === 'TEMPLATE_NOT_FOUND') {+ // Distinguish "inherited" (resolvable from an ancestor) — teach+ // localize-then-move — from "truly absent" — 404.+ const found = findTemplateLeafToRoot(+ fromValidated.resolvedContentDir,+ fromValidated.folderRel,+ body.fromName,+ );+ if (found?.scope === 'inherited') {+ errorResponse(+ res,+ 400,+ 'urn:ok:error:invalid-request',+ `Template "${body.fromName}" is inherited from "${found.folder || '(root)'}", not local to "${fromValidated.folderRel || '(root)'}". Move it from the folder that owns it, or create a local copy here first (then move that).`,+ { handler: 'template-move', detail: 'TEMPLATE_INHERITED' },+ );+ return;+ }+ errorResponse(res, 404, 'urn:ok:error:template-not-found', 'Template not found.', {+ handler: 'template-move',+ detail: result.error.message,+ });+ return;+ }+ if (result.error.code === 'TEMPLATE_EXISTS') {+ errorResponse(res, 409, 'urn:ok:error:doc-already-exists', result.error.message, {+ handler: 'template-move',+ detail: result.error.code,+ });+ return;+ }+ const status =+ result.error.code === 'WRITE_ERROR' || result.error.code === 'MOVE_FAILED' ? 500 : 400;+ errorResponse(+ res,+ status,+ status === 500 ? 'urn:ok:error:internal-server-error' : 'urn:ok:error:invalid-request',+ status === 500 ? 'Failed to move template.' : 'Invalid template move request.',+ {+ handler: 'template-move',+ detail: result.error.code,+ cause: new Error(result.error.message),+ },+ );+ return;+ }++ // Mark the source content doc removed (the move relocated its file) so a+ // stale tab on the old name redirects instead of offering to resurrect+ // it (parity with ordinary doc deletion).+ recentlyRemovedDocs?.setDeleted(templateDocNameFor(fromValidated.folderRel, body.fromName));++ // Optional atomic move+edit: rewrite the relocated template's content.+ // The move already succeeded and persisted the original content, so any+ // failure here is captured and reported AFTER the move is attributed —+ // the rename must not be lost because the edit step failed.+ let contentEditError: { code: string; message: string } | null = null;+ if (body.body !== undefined || body.frontmatter !== undefined) {+ // Preserve the existing (just-moved) body when only `frontmatter` is+ // supplied. If that body can't be read, SKIP the rewrite rather than+ // risk wiping it — defaulting to '' would re-introduce the body-loss+ // bug on a read error; the moved file keeps its original content.+ let writeBody: string | null;+ if (typeof body.body === 'string') {+ writeBody = body.body;+ } else {+ try {+ writeBody = instantiateDoc(+ readFileSync(resolve(toValidated.resolvedContentDir, result.toPath), 'utf-8'),+ );+ } catch {+ writeBody = null;+ }+ }+ if (writeBody === null) {+ contentEditError = {+ code: 'READ_FAILED',+ message:+ 'could not read the moved template to apply the metadata change; the move succeeded with the original content intact — retry the edit',+ };+ } else {+ const writeResult = applyTemplateWrite({+ projectDir: toValidated.resolvedContentDir,+ folder: toValidated.folderRel,+ name: body.toName,+ body: writeBody,+ frontmatter: pickFrontmatterFields(body.frontmatter) satisfies TemplateFrontmatter,+ });+ if (!writeResult.ok) contentEditError = writeResult.error;+ }+ }++ // Close the dropped-FSEvent gap for the DESTINATION (parity with+ // put/import): the relocate may have just created `toFolder`'s+ // `.ok/templates/` dir — the brand-new-subdir race where the watcher's+ // create event can be lost. Read the final on-disk bytes (post the+ // optional edit above) so the index entry matches what landed.+ // Best-effort like the helper itself: on a read failure the CRDT/disk+ // copy exists regardless and a rescan re-seeds the index.+ try {+ registerWrittenDocInFileIndex(+ templateDocNameFor(toValidated.folderRel, body.toName),+ readFileSync(resolve(toValidated.resolvedContentDir, result.toPath), 'utf-8'),+ );+ } catch {+ // Unreadable destination — leave index membership to the watcher.+ }++ // The move succeeded — attribute + commit + signal regardless of the+ // optional content edit's outcome, so the rename is never lost when the+ // edit step fails.+ attributeOkArtifactWrite(+ actor,+ okArtifactKey('template', toValidated.folderRel, body.toName),+ `template-rename: ${result.fromPath} -> ${result.toPath}`,+ [{ from: result.fromPath, to: result.toPath }],+ );+ scheduleOkArtifactFlush('template-move');+ signalChannel?.('files');++ if (contentEditError) {+ const isServerError =+ contentEditError.code === 'WRITE_ERROR' || contentEditError.code === 'READ_FAILED';+ errorResponse(+ res,+ isServerError ? 500 : 400,+ isServerError ? 'urn:ok:error:internal-server-error' : 'urn:ok:error:invalid-request',+ // Include the destination so the agent can retry the content edit+ // against the moved template without re-deriving where it landed.+ `Template moved to "${result.toPath}", but updating its content failed.`,+ {+ handler: 'template-move',+ detail: contentEditError.code,+ cause: new Error(contentEditError.message),+ },+ );+ return;+ }+ successResponse(+ res,+ 200,+ TemplateMoveSuccessSchema,+ { from: result.fromPath, to: result.toPath, committed: result.committed },+ { handler: 'template-move' },+ );+ } catch (e) {+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to move template.', {+ handler: 'template-move',+ cause: e,+ });+ }+ },+ { handler: 'template-move', method: 'POST' },+ );++ const handleTemplate = methodRouter(+ {+ GET: handleTemplateGet,+ PUT: handleTemplatePut,+ POST: handleTemplateMove,+ DELETE: handleTemplateDelete,+ },+ { handler: 'template' },+ );++ const handleTemplateImport = withValidation(+ TemplateImportRequestSchema,+ async (_req, res, body) => {+ try {+ if (ephemeral) {+ errorResponse(+ res,+ 403,+ 'urn:ok:error:single-file-mode',+ 'Templates are not available in single-file mode.',+ { handler: 'template-import' },+ );+ return;+ }++ const actor = extractActorIdentity(+ body as unknown as Record<string, unknown>,+ getPrincipal,+ );+ if (actor.kind === 'invalid-summary') {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {+ handler: 'template-import',+ });+ return;+ }++ const sourcePath = body.sourcePath;+ if (!isSafeDocName(sourcePath)) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid sourcePath.', {+ handler: 'template-import',+ });+ return;+ }++ const sourceDocName = resolveAlias(sourcePath);+ if (isSystemDoc(sourceDocName) || isConfigDoc(sourceDocName)) {+ errorResponse(+ res,+ 400,+ 'urn:ok:error:reserved-doc-name',+ `'${sourceDocName}' is a reserved document name.`,+ { handler: 'template-import' },+ );+ return;+ }++ const sourceFilePath = resolveContentEntryPath(contentDir, 'file', sourceDocName);+ if (!existsSync(sourceFilePath)) {+ errorResponse(+ res,+ 404,+ 'urn:ok:error:doc-not-found',+ `Source document not found: ${sourceDocName}.`,+ {+ handler: 'template-import',+ },+ );+ return;+ }++ const existing = hocuspocus.documents.get(sourceDocName);+ if (body.deleteSource) {+ const deleteEngine = getSyncEngine?.();+ const deleteTrackedFiles = new Set(+ deleteEngine ? deleteEngine.getConflicts().map((c) => c.file) : [],+ );+ const conflictedByLifecycle = existing !== undefined && isDocInConflict(existing);+ const conflictedByStore = deleteTrackedFiles.has(sourcePath);+ if (conflictedByLifecycle || conflictedByStore) {+ respondDocInConflict(+ res,+ new DocInConflictError({ file: sourcePath }),+ 'template-import',+ );+ return;+ }+ }++ // Read source content+ let sourceContent = '';+ if (existing) {+ sourceContent = existing.getText('source').toString();+ } else {+ const dc = await hocuspocus.openDirectConnection(sourceDocName);+ try {+ const document = dc.document;+ if (!document) {+ errorResponse(+ res,+ 500,+ 'urn:ok:error:doc-not-available',+ 'Source document is not available.',+ {+ handler: 'template-import',+ },+ );+ return;+ }+ sourceContent = document.getText('source').toString();+ } finally {+ await dc.disconnect();+ }+ }++ // Determine target template name+ let name = body.name;+ if (!name) {+ const { basename } = splitContentPath(sourcePath);+ const nameWithoutExt = basename.replace(/\.(md|mdx)$/i, '');+ name = nameWithoutExt.replace(/[^A-Za-z0-9_-]/g, '-').toLowerCase();+ name = name.replace(/^[-_]+|[-_]+$/g, '');+ name ||= 'imported-template';+ }++ if (!validateTemplateName(name, res, 'template-import')) return;++ const validated = validateFolderRel(body.targetFolder, res, 'folder', 'template-import');+ if (!validated) return;++ if (+ checkTemplateConflictGate(+ templateDocNameFor(validated.folderRel, name),+ 'template-import',+ res,+ )+ )+ return;++ // Parse existing frontmatter of the source file to extract the title/description/tags+ const { frontmatter: sourceFmText, body: sourceBody } = stripFrontmatter(sourceContent);+ const cleanFmText = unwrapFrontmatterFences(sourceFmText);+ let sourceFmObj: Record<string, unknown> = {};+ try {+ if (cleanFmText.trim()) {+ sourceFmObj = parseYaml(cleanFmText) as Record<string, unknown>;+ }+ } catch {+ // Malformed frontmatter — treat the source as having none.+ }++ const templateTitle =+ body.title || (sourceFmObj?.title as string) || extractPageTitle(sourceContent, name);+ const templateDescription = (sourceFmObj?.description as string) || '';+ const templateTags = Array.isArray(sourceFmObj?.tags) ? (sourceFmObj.tags as string[]) : [];++ // For the starter content, we can use the original document frontmatter but remove `template:`+ // if it somehow got there. Keep other fields. We also drop `title` so it doesn't get baked into every instance.+ const starterFmObj = { ...sourceFmObj };+ delete starterFmObj.template;+ delete starterFmObj.title;++ let starterContent = '';+ if (Object.keys(starterFmObj).length > 0) {+ const fmYaml = stringifyYaml(starterFmObj);+ starterContent = `${fmYaml.trim()}\n`;+ }+ starterContent = starterContent ? `---\n${starterContent}---\n${sourceBody}` : sourceBody;++ const composed = composeTemplateContent({+ name,+ body: starterContent,+ frontmatter: {+ title: templateTitle,+ description: templateDescription,+ tags: templateTags,+ },+ });++ if (!composed.ok) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid template request.', {+ handler: 'template-import',+ detail: composed.error.code,+ cause: new Error(composed.error.message),+ });+ return;+ }++ const templateFilePath = resolve(+ validated.resolvedContentDir,+ validated.folderRel,+ '.ok',+ 'templates',+ `${name}.md`,+ );+ const templateCreated = !existsSync(templateFilePath);+ const templateRelPath = relative(validated.resolvedContentDir, templateFilePath)+ .split(/[\\/]/)+ .filter(Boolean)+ .join('/');+ const templateDocName = templateDocNameFor(validated.folderRel, name);++ const { agentId, agentName, colorSeed, clientName } = extractAgentIdentity(+ body as unknown as Record<string, unknown>,+ );+ const templateSession = await sessionManager.getSession(templateDocName, agentId, {+ displayName: agentName,+ colorSeed,+ clientName,+ });+ templateSession.dc.document.transact(() => {+ composeAndWriteRawBody(templateSession.dc.document, composed.content, 'agent');+ }, templateSession.origin);++ const templateFlush = await flushDiskAndDetectOutcome(templateDocName);+ if (templateFlush?.kind === 'failure') {+ respondPersistenceFailure(res, templateFlush.failure, 'template-import');+ return;+ }+ if (templateFlush?.kind === 'divergence') {+ respondDiskDivergence(res, 'template-import');+ return;+ }++ // Close the dropped-FSEvent gap at the source (see helper): the flush+ // may have just created the target folder's `.ok/templates/` dir —+ // exactly the brand-new-subdir race where the watcher's create event+ // can be lost. Same net as the sibling agent-write handlers.+ registerWrittenDocInFileIndex(templateDocName, composed.content);++ attributeOkArtifactWrite(+ actor,+ okArtifactKey('template', validated.folderRel, name),+ `template-import: ${templateRelPath}`,+ );++ if (body.deleteSource) {+ const deletedDocNames = [sourceDocName];+ await captureAndCloseDocuments(deletedDocNames, 'deleted-upstream');+ if (recentlyRemovedDocs) {+ recentlyRemovedDocs.setDeleted(sourceDocName);+ }+ tracedUnlinkSync(sourceFilePath);+ mutateFileIndex?.({+ kind: 'delete',+ path: sourceFilePath,+ docName: sourceDocName,+ });+ }++ scheduleOkArtifactFlush('template-import');+ signalChannel?.('files');++ successResponse(+ res,+ 200,+ TemplateImportSuccessSchema,+ {+ path: templateRelPath,+ created: templateCreated,+ warnings: composed.warnings,+ },+ { handler: 'template-import' },+ );+ } catch (e) {+ errorResponse(+ res,+ 500,+ 'urn:ok:error:internal-server-error',+ 'Failed to import template.',+ {+ handler: 'template-import',+ cause: e,+ },+ );+ }+ },+ { handler: 'template-import', method: 'POST' },+ );++ return createApiRouteGroup(+ {+ '/api/folder-config': handleFolderConfig,+ '/api/template': handleTemplate,+ '/api/template/import': handleTemplateImport,+ },+ {+ mutating: ['/api/folder-config', '/api/template', '/api/template/import'],+ },+ );+}diff --git a/packages/server/src/http/seed-routes.test.ts b/packages/server/src/http/seed-routes.test.tsnew file mode 100644index 000000000..8b5f38457--- /dev/null+++ b/packages/server/src/http/seed-routes.test.ts@@ -0,0 +1,42 @@+import { describe, expect, test } from 'vitest';+import { createSeedRoutes } from './seed-routes.ts';++/**+ * Table-level pins for the seed group's mutating declaration. The wire cannot+ * pin this: the read half of the DNS-rebinding defense applies the identical+ * loopback + workspace-Host checks to every `/api/*` request, so an emptied+ * mutating set changes no composition-suite response — only which gate (and+ * telemetry tag) fires first. The declared membership is pinned here directly+ * against the legacy `MUTATING_ROUTES` membership it reproduces.+ */++function buildGroup() {+ return createSeedRoutes({+ contentDir: '/nonexistent-content',+ // Never dispatched by these pins; the table declaration is what's under test.+ checkLocalOpSecurity: () => false,+ });+}++describe('createSeedRoutes table', () => {+ test('registers exactly the four seed paths', () => {+ expect([...buildGroup().paths].sort()).toEqual(+ [+ '/api/seed/plan',+ '/api/seed/apply',+ '/api/seed/install-pack-skill',+ '/api/seed/packs',+ ].sort(),+ );+ });++ test('legacy MUTATING_ROUTES members are mutating; the reads are not', () => {+ const { table } = buildGroup();+ for (const path of ['/api/seed/apply', '/api/seed/install-pack-skill']) {+ expect(table.isMutating(path), path).toBe(true);+ }+ for (const path of ['/api/seed/plan', '/api/seed/packs']) {+ expect(table.isMutating(path), path).toBe(false);+ }+ });+});diff --git a/packages/server/src/http/seed-routes.ts b/packages/server/src/http/seed-routes.tsnew file mode 100644index 000000000..fc5bfaf00--- /dev/null+++ b/packages/server/src/http/seed-routes.ts@@ -0,0 +1,265 @@+/**+ * The `ok seed` scaffolder family — `seed/plan`, `seed/packs` (reads) plus+ * `seed/apply`, `seed/install-pack-skill` (mutating) — natively routed as one+ * group. What the handlers reach for arrives as {@link SeedRouteDeps}.+ *+ * All four handlers gate on `checkLocalOpSecurity` INLINE (the two reads run+ * it ahead of method dispatch; the two writers run it as a `preBodyGate`), so+ * the whole family is loopback-confined regardless of the table's mutating+ * declaration — `mutating` below reproduces the legacy `MUTATING_ROUTES`+ * membership (`seed/apply`, `seed/install-pack-skill`) so the pipeline-level+ * gate and its telemetry tag are unchanged across the lift.+ */++import type { IncomingMessage, ServerResponse } from 'node:http';+import {+ SeedApplyRequestSchema,+ SeedApplySuccessSchema,+ SeedInstallPackSkillRequestSchema,+ SeedInstallPackSkillSuccessSchema,+ SeedListPacksSuccessSchema,+ SeedPlanSuccessSchema,+} from '@inkeep/open-knowledge-core';+import {+ applySeed,+ coercePackId,+ installPackSkillOnDemand,+ listStarterPacks,+ planSeed,+ type ScaffoldPlan,+ SeedPrerequisiteError,+ SeedRootDirError,+} from '../seed/index.ts';+import { type ApiRouteGroup, createApiRouteGroup } from './api-pipeline.ts';+import { errorResponse } from './error-response.ts';+import { withValidation } from './request-validation.ts';+import { successResponse } from './success-response.ts';++export interface SeedRouteDeps {+ contentDir: string;+ /** The extension's shared local-op security gate (emits RFC 9457 on refusal). */+ checkLocalOpSecurity: (+ req: IncomingMessage,+ res: ServerResponse,+ opts: { handler: string },+ ) => boolean;+}++export function createSeedRoutes(deps: SeedRouteDeps): ApiRouteGroup {+ const { contentDir, checkLocalOpSecurity } = deps;++ // ─── `ok seed` scaffolder endpoints ──────────────────────────────────────+ // GET /api/seed/plan → 200 {plan} (RFC 9457 problem+json on error)+ // POST /api/seed/apply with { plan } → 200 {result} (RFC 9457 problem+json on error)+ //+ // Same `planSeed` / `applySeed` logic the CLI subcommand and Electron IPC+ // handler use. The IPC bridge (`ok:seed:plan` / `ok:seed:apply`) keeps its+ // in-process discriminated-union shape (`{ok: true, plan}` / `{ok: false,+ // error: {kind, message}}`); the HTTP fallback in `seedClient()` translates+ // RFC 9457 problem+json back to that shape at the renderer boundary so+ // `SeedDialog` / `EmptyEditorState` are transport-agnostic.+ // Gated on `checkLocalOpSecurity` because the operation mutates the local+ // filesystem; same contract as /api/local-op/* and /api/installed-agents.++ /**+ * GET `/api/seed/plan?rootDir=brain&packId=software-lifecycle` — preview the+ * scaffold for a given subfolder + pack. `rootDir` defaults to `.` (project+ * root). `packId` defaults to the registry default (`'knowledge-base'`) for+ * back-compat with single-scaffold callers; unknown ids coerce to undefined+ * and `resolvePack()` falls back to the default.+ *+ * Prerequisite-missing (no git init) → 422 with+ * `urn:ok:error:seed-prerequisite-missing`; invalid-root (escape segments,+ * absolute path) → 400 with `urn:ok:error:seed-invalid-root`. Both surface+ * a `detail` carrying the underlying message so renderers can echo it.+ */+ async function handleSeedPlan(req: IncomingMessage, res: ServerResponse): Promise<void> {+ if (!checkLocalOpSecurity(req, res, { handler: 'seed-plan' })) return;+ if (req.method !== 'GET') {+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {+ handler: 'seed-plan',+ extraHeaders: { Allow: 'GET' },+ });+ return;+ }+ const url = new URL(req.url ?? '/', 'http://localhost');+ const rootDir = url.searchParams.get('rootDir') ?? undefined;+ const rawPackId = url.searchParams.get('packId');+ const packId = coercePackId(rawPackId);+ // Trust-boundary symmetry with the CLI: if the caller passed a `packId`+ // but it doesn't name a registered pack, reject explicitly rather than+ // silently fall back to the default pack (CLI returns "Unknown pack"+ // failure on the same input).+ if (rawPackId !== null && rawPackId !== '' && packId === undefined) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Unknown packId.', {+ handler: 'seed-plan',+ detail: `Pack id "${rawPackId}" is not registered.`,+ });+ return;+ }+ try {+ const plan = await planSeed({ projectDir: contentDir, rootDir, packId });+ successResponse(res, 200, SeedPlanSuccessSchema, { plan }, { handler: 'seed-plan' });+ } catch (err) {+ if (err instanceof SeedPrerequisiteError) {+ errorResponse(+ res,+ 422,+ 'urn:ok:error:seed-prerequisite-missing',+ 'Seed prerequisite missing.',+ { handler: 'seed-plan', cause: err },+ );+ return;+ }+ if (err instanceof SeedRootDirError) {+ // Fixed-vocabulary safe `detail` per RFC 9457 §3.1.5 — gives the+ // client an actionable message without leaking the rejected path+ // (raw err message goes through `cause` → Pino, never on wire).+ errorResponse(res, 400, 'urn:ok:error:seed-invalid-root', 'Invalid seed root directory.', {+ handler: 'seed-plan',+ detail: 'The provided root directory is not within the workspace content directory.',+ cause: err,+ });+ return;+ }+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'seed-plan',+ cause: err,+ });+ }+ }++ /**+ * `POST /api/seed/apply` — apply a pre-computed ScaffoldPlan to disk.+ * Body accepts `{plan, packId?}` (extras pass through+ * `SeedApplyRequestSchema.loose()`); `packId` defaults to the registry+ * default.+ */+ const handleSeedApply = withValidation(+ SeedApplyRequestSchema,+ async (_req, res, body) => {+ // SeedApplyRequestSchema accepts `plan: unknown` (forward-compat); reject+ // non-object payloads here so applySeed sees a structured value.+ const planValue = body.plan;+ if (!planValue || typeof planValue !== 'object') {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid plan payload.', {+ handler: 'seed-apply',+ });+ return;+ }+ const plan = planValue as ScaffoldPlan;+ // SeedApplyRequestSchema is `.loose()` so extras flow through as `unknown`+ // on the parsed body; coerce defensively at the trust boundary. If the+ // caller passed a non-empty `packId` that doesn't name a registered+ // pack, reject explicitly (trust-boundary symmetry with the CLI, which+ // returns an "Unknown pack" failure on the same input).+ const looseBody = body as { packId?: unknown };+ const rawPackId = looseBody.packId;+ const packId = coercePackId(rawPackId);+ if (typeof rawPackId === 'string' && rawPackId.length > 0 && packId === undefined) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Unknown packId.', {+ handler: 'seed-apply',+ detail: `Pack id "${rawPackId}" is not registered.`,+ });+ return;+ }+ try {+ // The plan already has rootDir baked into its entries — apply only+ // needs projectDir + packId (so it knows which template registry to+ // resolve content from).+ const result = await applySeed(plan, { projectDir: contentDir, packId });+ successResponse(res, 200, SeedApplySuccessSchema, { result }, { handler: 'seed-apply' });+ } catch (err) {+ errorResponse(+ res,+ 500,+ 'urn:ok:error:internal-server-error',+ 'Failed to apply seed plan.',+ {+ handler: 'seed-apply',+ cause: err,+ },+ );+ }+ },+ {+ handler: 'seed-apply',+ method: 'POST',+ preBodyGate: (req, res) => checkLocalOpSecurity(req, res, { handler: 'seed-apply' }),+ },+ );++ /**+ * `POST /api/seed/install-pack-skill` — install only a pack's companion+ * skills. It deliberately skips scaffold files and required-plugin changes:+ * the settings card is a separate user-owned install action, not a replay of+ * `ok seed` and not a side effect of the plugin toggle.+ */+ const handleSeedInstallPackSkill = withValidation(+ SeedInstallPackSkillRequestSchema,+ async (_req, res, body) => {+ const packId = coercePackId(body.packId);+ if (packId === undefined) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Unknown packId.', {+ handler: 'seed-install-pack-skill',+ detail: `Pack id "${body.packId}" is not registered.`,+ });+ return;+ }+ try {+ const result = await installPackSkillOnDemand(contentDir, packId);+ successResponse(res, 200, SeedInstallPackSkillSuccessSchema, result, {+ handler: 'seed-install-pack-skill',+ });+ } catch (err) {+ errorResponse(+ res,+ 500,+ 'urn:ok:error:internal-server-error',+ 'Failed to install pack skill.',+ { handler: 'seed-install-pack-skill', cause: err },+ );+ }+ },+ {+ handler: 'seed-install-pack-skill',+ method: 'POST',+ preBodyGate: (req, res) =>+ checkLocalOpSecurity(req, res, { handler: 'seed-install-pack-skill' }),+ },+ );++ /**+ * `GET /api/seed/packs` — enumerate available starter packs. Static data;+ * no project context required. The picker UI fetches once on dialog mount.+ * Delegates to the shared `listStarterPacks()` so HTTP + IPC return the+ * same wire-format shape from one source.+ */+ async function handleSeedPacks(req: IncomingMessage, res: ServerResponse): Promise<void> {+ if (!checkLocalOpSecurity(req, res, { handler: 'seed-packs' })) return;+ if (req.method !== 'GET') {+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {+ handler: 'seed-packs',+ extraHeaders: { Allow: 'GET' },+ });+ return;+ }+ successResponse(+ res,+ 200,+ SeedListPacksSuccessSchema,+ { packs: listStarterPacks() },+ { handler: 'seed-packs' },+ );+ }++ return createApiRouteGroup(+ {+ '/api/seed/plan': handleSeedPlan,+ '/api/seed/apply': handleSeedApply,+ '/api/seed/install-pack-skill': handleSeedInstallPackSkill,+ '/api/seed/packs': handleSeedPacks,+ },+ { mutating: ['/api/seed/apply', '/api/seed/install-pack-skill'] },+ );+}diff --git a/packages/server/src/http/system-actions-routes.test.ts b/packages/server/src/http/system-actions-routes.test.tsnew file mode 100644index 000000000..e893fedcf--- /dev/null+++ b/packages/server/src/http/system-actions-routes.test.ts@@ -0,0 +1,43 @@+import { describe, expect, test } from 'vitest';+import { loggerFactory } from '../logger.ts';+import { createSystemActionsRoutes } from './system-actions-routes.ts';++/**+ * Table-level pins for the system-actions group's mutating declaration. The+ * wire cannot pin this: the read half of the DNS-rebinding defense applies+ * the identical loopback + workspace-Host checks to every `/api/*` request,+ * so an emptied mutating set changes no composition-suite response — only+ * which gate (and telemetry tag) fires first. The declared membership is+ * pinned here directly against the legacy `MUTATING_ROUTES` membership it+ * reproduces — `spawn-cursor` and `handoff` were deliberately NOT members+ * (their loopback confinement is the in-handler `checkLocalOpSecurity`+ * first line), and that posture must survive the lift byte-for-byte.+ */++function buildGroup() {+ return createSystemActionsRoutes({+ contentDir: '/nonexistent-content',+ log: loggerFactory.getLogger('test'),+ // Never dispatched by these pins; the table declaration is what's under test.+ checkLocalOpSecurity: () => false,+ installedAgentsCache: {+ probeWithCache: () => Promise.resolve(false),+ },+ });+}++describe('createSystemActionsRoutes table', () => {+ test('registers exactly the three system-action paths', () => {+ expect([...buildGroup().paths].sort()).toEqual(+ ['/api/spawn-cursor', '/api/handoff', '/api/client-logs'].sort(),+ );+ });++ test('only client-logs reproduces legacy MUTATING_ROUTES membership', () => {+ const { table } = buildGroup();+ expect(table.isMutating('/api/client-logs')).toBe(true);+ for (const path of ['/api/spawn-cursor', '/api/handoff']) {+ expect(table.isMutating(path), path).toBe(false);+ }+ });+});diff --git a/packages/server/src/http/system-actions-routes.ts b/packages/server/src/http/system-actions-routes.tsnew file mode 100644index 000000000..5d5e853dd--- /dev/null+++ b/packages/server/src/http/system-actions-routes.ts@@ -0,0 +1,190 @@+/**+ * The editor-host system-action pair — `spawn-cursor`, `handoff` — plus the+ * renderer log-ingest sink `client-logs`, routed as one small group (three+ * single-route families, following the `workspace-tools-routes.ts` bundling+ * precedent). What the handlers reach for arrives as+ * {@link SystemActionsRouteDeps}.+ *+ * `spawn-cursor` and `handoff` are not `mutating` members — each carries the+ * loopback-peer + Origin local-op gate INLINE as its first line+ * (`checkLocalOpSecurity`), so both spawn binaries only for same-machine+ * callers while staying on the read posture at the table tier. The+ * workspace-Host half of the DNS-rebinding defense comes from the pipeline's+ * universal `/api/*` read gate, not from the handler. `mutating` below declares+ * only `client-logs`, reproducing the legacy `MUTATING_ROUTES` membership+ * exactly. The handoff handler shares the extension's `installedAgentsCache`+ * scheme probe by reference, so its 60s TTL stays agreed with the+ * `/api/installed-agents` dropdown gate.+ */++import type { IncomingMessage, ServerResponse } from 'node:http';+import { ClientLogsRequestSchema, ClientLogsSuccessSchema } from '@inkeep/open-knowledge-core';+import type { createInstalledAgentsProbe } from '../handoff-api.ts';+import { handleHandoffDispatch } from '../handoff-dispatch-api.ts';+import { getLogger, type PinoLogger } from '../logger.ts';+import { handleSpawnCursor } from '../spawn-cursor-api.ts';+import { type ApiRouteGroup, createApiRouteGroup } from './api-pipeline.ts';+import { errorResponse } from './error-response.ts';+import { getRequestId } from './request-id.ts';+import { withValidation } from './request-validation.ts';+import { successResponse } from './success-response.ts';++export interface SystemActionsRouteDeps {+ contentDir: string;+ log: PinoLogger;+ /** The extension's shared local-op security gate (emits RFC 9457 on refusal). */+ checkLocalOpSecurity: (+ req: IncomingMessage,+ res: ServerResponse,+ opts: { handler: string },+ ) => boolean;+ /**+ * The extension's shared scheme-probe cache — the SAME object+ * `/api/installed-agents` reads, so the dispatch availability gate and the+ * dropdown's render gate agree (and share the 60s TTL). Narrowed to the one+ * member the handoff dispatch consults.+ */+ installedAgentsCache: Pick<ReturnType<typeof createInstalledAgentsProbe>, 'probeWithCache'>;+}++export function createSystemActionsRoutes(deps: SystemActionsRouteDeps): ApiRouteGroup {+ const { contentDir, log, checkLocalOpSecurity, installedAgentsCache } = deps;++ async function handleHandoffDispatchRoute(+ req: IncomingMessage,+ res: ServerResponse,+ ): Promise<void> {+ // Loopback-only gate — spawns binaries on the user's machine. Same model+ // as `/api/spawn-cursor` and `/api/installed-agents`. The handler also+ // enforces app-name allowlist + URL scheme matching + cursor path+ // containment as defense-in-depth.+ if (!checkLocalOpSecurity(req, res, { handler: 'handoff' })) return;+ try {+ await handleHandoffDispatch(req, res, {+ contentDir,+ platform: process.platform,+ // Share the same cached scheme probe `/api/installed-agents` uses so+ // the Windows/Linux dispatch availability gate agrees with the+ // dropdown's render gate (and reuses its 60s TTL — the row the user+ // just saw enabled decides the click). Unused on macOS.+ isSchemeRegistered: installedAgentsCache.probeWithCache,+ });+ } catch (e) {+ if (!res.headersSent) {+ log.error({ err: e, requestId: getRequestId(req) }, '[handoff] route wrapper failed');+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'handoff',+ cause: e,+ });+ }+ }+ }++ async function handleSpawnCursorRoute(req: IncomingMessage, res: ServerResponse): Promise<void> {+ // Same loopback + DNS-rebinding gate as `/api/installed-agents` — this+ // endpoint spawns a binary on the user's machine, so confining callers+ // to same-origin loopback is load-bearing. Path containment + hardcoded+ // `cursor` binary + `shell:false` argv-array enforce the rest of the+ // security model inside `handleSpawnCursor`. See the file-level comment+ // in `./spawn-cursor-api.ts` for the full threat model.+ // `checkLocalOpSecurity` itself emits RFC 9457 problem+json on rejection.+ if (!checkLocalOpSecurity(req, res, { handler: 'spawn-cursor' })) return;+ try {+ await handleSpawnCursor(req, res, {+ contentDir,+ platform: process.platform,+ });+ } catch (e) {+ // Defensive: `handleSpawnCursor` emits RFC 9457 problem+json for every+ // expected failure mode internally. This catches truly unexpected+ // throws (e.g., a `resolveCursorBinary` injection that throws+ // synchronously) so the client still receives a typed contract+ // response instead of a hung connection. Mirrors `handleInstalledAgentsRoute`.+ if (!res.headersSent) {+ log.error({ err: e, requestId: getRequestId(req) }, '[spawn-cursor] route wrapper failed');+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'spawn-cursor',+ cause: e,+ });+ }+ }+ }++ // Web/browser client-log ingest: the renderer forwarder POSTs batches of+ // captured `console` output here, written to the `renderer` pino subsystem+ // (→ the local-sink server log). Electron captures renderer console in its+ // main process instead. Writes no Y.Docs — exempt from attribution; gated by+ // `checkLocalOpSecurity` (loopback-peer + Origin) as a preBodyGate, with the+ // workspace-Host check added by the shared pipeline mutating gate.+ const handleClientLogs = withValidation(+ ClientLogsRequestSchema,+ async (_req, res, body) => {+ try {+ const logger = getLogger('renderer');+ if (body.droppedSinceLastFlush !== undefined && body.droppedSinceLastFlush > 0) {+ // Gap marker: the forwarder lost entries (buffer overflow / failed+ // POSTs) between the previous delivered batch and this one. Persist+ // it as its own line so a log reader knows the silence was loss,+ // not inactivity.+ logger.warn(+ {+ source: 'renderer-console',+ transport: 'web',+ event: 'client-log-entries-dropped',+ droppedSinceLastFlush: body.droppedSinceLastFlush,+ },+ 'client-log-entries-dropped',+ );+ }+ for (const entry of body.entries) {+ // Per-entry guard: one entry that trips a pino serialization fault+ // must not drop the rest of the batch (the response still reports the+ // full accepted count — best-effort diagnostics ingest).+ try {+ // Spread client `fields` FIRST so the provenance markers below+ // always win (a client field must not clobber source/transport).+ logger[entry.level](+ {+ ...entry.fields,+ source: 'renderer-console',+ transport: 'web',+ ...(entry.sourceId ? { sourceId: entry.sourceId } : {}),+ ...(entry.lineNumber !== undefined ? { lineNumber: entry.lineNumber } : {}),+ ...(entry.ts !== undefined ? { clientTs: entry.ts } : {}),+ },+ entry.event ?? entry.message,+ );+ } catch {+ // Skip the malformed entry; continue the batch.+ }+ }+ successResponse(+ res,+ 200,+ ClientLogsSuccessSchema,+ { accepted: body.entries.length },+ { handler: 'client-logs' },+ );+ } catch (err) {+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'client-logs',+ cause: err,+ });+ }+ },+ {+ handler: 'client-logs',+ method: 'POST',+ preBodyGate: (req, res) => checkLocalOpSecurity(req, res, { handler: 'client-logs' }),+ },+ );++ return createApiRouteGroup(+ {+ '/api/spawn-cursor': handleSpawnCursorRoute,+ '/api/handoff': handleHandoffDispatchRoute,+ '/api/client-logs': handleClientLogs,+ },+ { mutating: ['/api/client-logs'] },+ );+}