feat: Add File Organization settings section with output template input…

- "src/frontend/src/pages/Settings.tsx"
- "src/frontend/src/components/FormatProfileForm.tsx"
- "src/frontend/src/api/hooks/useFormatProfiles.ts"
- "src/types/api.ts"
- "src/server/routes/system.ts"

GSD-Task: S02/T04

src/frontend/src/api/hooks/useFormatProfiles.ts

@@ -29,6 +29,7 @@ interface CreateFormatProfileInput {
   isDefault?: boolean;
   subtitleLanguages?: string | null;
   embedSubtitles?: boolean;
+  outputTemplate?: string | null;
 }
 
 interface UpdateFormatProfileInput {
@@ -40,6 +41,7 @@ interface UpdateFormatProfileInput {
   isDefault?: boolean;
   subtitleLanguages?: string | null;
   embedSubtitles?: boolean;
+  outputTemplate?: string | null;
 }
 
 // ── Mutations ──

src/frontend/src/components/FormatProfileForm.tsx

@@ -1,4 +1,4 @@
-import { useState, useCallback, type FormEvent } from 'react';
+import { useState, useCallback, useMemo, type FormEvent } from 'react';
 import { Loader } from 'lucide-react';
 import type { FormatProfile } from '@shared/types/index';
 
@@ -23,6 +23,7 @@ export interface FormatProfileFormValues {
   embedChapters: boolean;
   embedThumbnail: boolean;
   sponsorBlockRemove: string | null;
+  outputTemplate: string | null;
 }
 
 interface FormatProfileFormProps {
@@ -98,6 +99,38 @@ export function FormatProfileForm({
   const [embedChapters, setEmbedChapters] = useState(profile?.embedChapters ?? false);
   const [embedThumbnail, setEmbedThumbnail] = useState(profile?.embedThumbnail ?? false);
   const [sponsorBlockRemove, setSponsorBlockRemove] = useState(profile?.sponsorBlockRemove ?? '');
+  const [outputTemplate, setOutputTemplate] = useState(profile?.outputTemplate ?? '');
+
+  const TEMPLATE_VARIABLES = ['platform', 'channel', 'title', 'date', 'year', 'month', 'contentType', 'id', 'ext'] as const;
+
+  const templatePreview = useMemo(() => {
+    if (!outputTemplate.trim()) return '';
+    const exampleVars: Record<string, string> = {
+      platform: 'youtube',
+      channel: 'TechChannel',
+      title: 'How to Build a Server',
+      date: '2026-04-04',
+      year: '2026',
+      month: '04',
+      contentType: 'video',
+      id: 'dQw4w9WgXcQ',
+      ext: 'mp4',
+    };
+    return outputTemplate.replace(/\{([a-zA-Z]+)\}/g, (_m, v: string) => exampleVars[v] ?? `{${v}}`);
+  }, [outputTemplate]);
+
+  const templateErrors = useMemo(() => {
+    if (!outputTemplate.trim()) return []; // empty = use system default
+    const errors: string[] = [];
+    if (!outputTemplate.includes('{ext}')) errors.push('Must contain {ext}');
+    const matches = [...outputTemplate.matchAll(/\{([a-zA-Z]+)\}/g)];
+    for (const m of matches) {
+      if (!(TEMPLATE_VARIABLES as readonly string[]).includes(m[1])) {
+        errors.push(`Unknown variable: {${m[1]}}`);
+      }
+    }
+    return errors;
+  }, [outputTemplate]);
 
   const handleSubmit = useCallback(
     (e: FormEvent) => {
@@ -115,9 +148,10 @@ export function FormatProfileForm({
         embedChapters,
         embedThumbnail,
         sponsorBlockRemove: sponsorBlockRemove.trim() || null,
+        outputTemplate: outputTemplate.trim() || null,
       });
     },
-    [name, videoResolution, audioCodec, audioBitrate, containerFormat, isDefault, subtitleLanguages, embedSubtitles, embedChapters, embedThumbnail, sponsorBlockRemove, onSubmit],
+    [name, videoResolution, audioCodec, audioBitrate, containerFormat, isDefault, subtitleLanguages, embedSubtitles, embedChapters, embedThumbnail, sponsorBlockRemove, outputTemplate, onSubmit],
   );
 
   return (
@@ -312,6 +346,39 @@ export function FormatProfileForm({
         </span>
       </div>
 
+      {/* Output Template (per-profile override) */}
+      <div style={fieldGroupStyle}>
+        <label htmlFor="fp-output-template" style={labelStyle}>
+          Output Template Override
+        </label>
+        <input
+          id="fp-output-template"
+          type="text"
+          value={outputTemplate}
+          onChange={(e) => setOutputTemplate(e.target.value)}
+          placeholder="Leave blank to use system default"
+          style={{
+            ...inputStyle,
+            fontFamily: 'var(--font-mono, "SF Mono", "Fira Code", monospace)',
+            fontSize: 'var(--font-size-sm)',
+            borderColor: templateErrors.length > 0 ? 'var(--danger)' : undefined,
+          }}
+        />
+        {templateErrors.length > 0 && (
+          <span style={{ fontSize: 'var(--font-size-xs)', color: 'var(--danger)', marginTop: 'var(--space-1)', display: 'block' }}>
+            {templateErrors.join('. ')}
+          </span>
+        )}
+        {templatePreview && templateErrors.length === 0 && (
+          <span style={{ fontSize: 'var(--font-size-xs)', color: 'var(--text-muted)', marginTop: 'var(--space-1)', display: 'block', fontFamily: 'var(--font-mono, "SF Mono", "Fira Code", monospace)' }}>
+            Preview: {templatePreview}
+          </span>
+        )}
+        <span style={{ fontSize: 'var(--font-size-xs)', color: 'var(--text-muted)', marginTop: 'var(--space-1)', display: 'block' }}>
+          Variables: {'{platform}'}, {'{channel}'}, {'{title}'}, {'{date}'}, {'{year}'}, {'{month}'}, {'{contentType}'}, {'{id}'}, {'{ext}'}
+        </span>
+      </div>
+
       {/* Is Default checkbox */}
       <div style={{ ...fieldGroupStyle, display: 'flex', alignItems: 'center', gap: 'var(--space-2)' }}>
         <input

src/frontend/src/pages/Settings.tsx

@@ -1,5 +1,5 @@
 import { useState, useCallback, useMemo, useEffect } from 'react';
-import { Plus, Pencil, Trash2, Loader, RefreshCw, Star, Bell, Send, CheckCircle, XCircle, Eye, EyeOff, Copy, RotateCw, Key, Globe, Save } from 'lucide-react';
+import { Plus, Pencil, Trash2, Loader, RefreshCw, Star, Bell, Send, CheckCircle, XCircle, Eye, EyeOff, Copy, RotateCw, Key, Globe, Save, FolderTree } from 'lucide-react';
 import {
   useFormatProfiles,
   useCreateFormatProfile,
@@ -83,6 +83,7 @@ export function SettingsPage() {
   const updateAppSettingsMutation = useUpdateAppSettings();
   const [checkInterval, setCheckInterval] = useState<number | ''>('');
   const [concurrentDownloads, setConcurrentDownloads] = useState<number | ''>('');
+  const [outputTemplate, setOutputTemplate] = useState('');
   const [settingsSaveFlash, setSettingsSaveFlash] = useState(false);
 
   // Initialize local state from fetched app settings
@@ -90,6 +91,7 @@ export function SettingsPage() {
     if (appSettings) {
       setCheckInterval(appSettings.checkInterval);
       setConcurrentDownloads(appSettings.concurrentDownloads);
+      setOutputTemplate(appSettings.outputTemplate);
     }
   }, [appSettings]);
 
@@ -98,14 +100,48 @@ export function SettingsPage() {
     concurrentDownloads !== '' &&
     appSettings != null &&
     (Number(checkInterval) !== appSettings.checkInterval ||
-      Number(concurrentDownloads) !== appSettings.concurrentDownloads);
+      Number(concurrentDownloads) !== appSettings.concurrentDownloads ||
+      outputTemplate !== appSettings.outputTemplate);
 
   const settingsValid =
     checkInterval !== '' &&
     concurrentDownloads !== '' &&
     Number(checkInterval) >= 1 &&
     Number(concurrentDownloads) >= 1 &&
-    Number(concurrentDownloads) <= 10;
+    Number(concurrentDownloads) <= 10 &&
+    outputTemplate.trim().length > 0 &&
+    outputTemplate.includes('{ext}');
+
+  // ── Template preview ──
+  const TEMPLATE_VARIABLES = ['platform', 'channel', 'title', 'date', 'year', 'month', 'contentType', 'id', 'ext'] as const;
+
+  const templatePreview = useMemo(() => {
+    const exampleVars: Record<string, string> = {
+      platform: 'youtube',
+      channel: 'TechChannel',
+      title: 'How to Build a Server',
+      date: '2026-04-04',
+      year: '2026',
+      month: '04',
+      contentType: 'video',
+      id: 'dQw4w9WgXcQ',
+      ext: 'mp4',
+    };
+    return outputTemplate.replace(/\{([a-zA-Z]+)\}/g, (_m, v: string) => exampleVars[v] ?? `{${v}}`);
+  }, [outputTemplate]);
+
+  const templateErrors = useMemo(() => {
+    const errors: string[] = [];
+    if (outputTemplate.trim().length === 0) return ['Template must not be empty'];
+    if (!outputTemplate.includes('{ext}')) errors.push('Must contain {ext}');
+    const matches = [...outputTemplate.matchAll(/\{([a-zA-Z]+)\}/g)];
+    for (const m of matches) {
+      if (!(TEMPLATE_VARIABLES as readonly string[]).includes(m[1])) {
+        errors.push(`Unknown variable: {${m[1]}}`);
+      }
+    }
+    return errors;
+  }, [outputTemplate]);
 
   // ── App Settings handlers ──
 
@@ -115,6 +151,7 @@ export function SettingsPage() {
       {
         checkInterval: Number(checkInterval),
         concurrentDownloads: Number(concurrentDownloads),
+        outputTemplate,
       },
       {
         onSuccess: () => {
@@ -836,6 +873,134 @@ export function SettingsPage() {
         </p>
       </section>
 
+      {/* ── File Organization section ── */}
+      <section style={{ marginBottom: 'var(--space-8)' }}>
+        <div style={{ marginBottom: 'var(--space-4)' }}>
+          <h2 style={{ display: 'flex', alignItems: 'center', gap: 'var(--space-2)', fontSize: 'var(--font-size-lg)', fontWeight: 600, color: 'var(--text-primary)' }}>
+            <FolderTree size={20} />
+            File Organization
+          </h2>
+          <p style={{ color: 'var(--text-muted)', fontSize: 'var(--font-size-sm)', marginTop: 'var(--space-1)' }}>
+            Configure the default output path template for downloaded files. Individual format profiles can override this.
+          </p>
+        </div>
+
+        <div
+          style={{
+            backgroundColor: 'var(--bg-card)',
+            borderRadius: 'var(--radius-xl)',
+            border: '1px solid var(--border)',
+            padding: 'var(--space-4)',
+          }}
+        >
+          {/* Template input */}
+          <div style={{ marginBottom: 'var(--space-4)' }}>
+            <label
+              htmlFor="output-template"
+              style={{
+                display: 'block',
+                fontSize: 'var(--font-size-sm)',
+                fontWeight: 500,
+                color: 'var(--text-secondary)',
+                marginBottom: 'var(--space-1)',
+              }}
+            >
+              Output Template
+            </label>
+            <input
+              id="output-template"
+              type="text"
+              value={outputTemplate}
+              onChange={(e) => setOutputTemplate(e.target.value)}
+              placeholder="{platform}/{channel}/{title}.{ext}"
+              aria-label="Output path template"
+              style={{
+                width: '100%',
+                padding: 'var(--space-2) var(--space-3)',
+                borderRadius: 'var(--radius-md)',
+                border: `1px solid ${templateErrors.length > 0 ? 'var(--danger)' : 'var(--border)'}`,
+                backgroundColor: 'var(--bg-main)',
+                color: 'var(--text-primary)',
+                fontSize: 'var(--font-size-sm)',
+                fontFamily: 'var(--font-mono, "SF Mono", "Fira Code", monospace)',
+              }}
+            />
+            {templateErrors.length > 0 && (
+              <div style={{ color: 'var(--danger)', fontSize: 'var(--font-size-xs)', marginTop: 'var(--space-1)' }}>
+                {templateErrors.join('. ')}
+              </div>
+            )}
+          </div>
+
+          {/* Available variables */}
+          <div style={{ marginBottom: 'var(--space-4)' }}>
+            <span style={{ fontSize: 'var(--font-size-xs)', color: 'var(--text-muted)', marginBottom: 'var(--space-2)', display: 'block' }}>
+              Available variables
+            </span>
+            <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--space-1)' }}>
+              {TEMPLATE_VARIABLES.map((v) => (
+                <button
+                  key={v}
+                  type="button"
+                  onClick={() => {
+                    const input = document.getElementById('output-template') as HTMLInputElement | null;
+                    if (input) {
+                      const start = input.selectionStart ?? outputTemplate.length;
+                      const end = input.selectionEnd ?? outputTemplate.length;
+                      const newVal = outputTemplate.slice(0, start) + `{${v}}` + outputTemplate.slice(end);
+                      setOutputTemplate(newVal);
+                      // Restore cursor position after React re-render
+                      requestAnimationFrame(() => {
+                        input.focus();
+                        const newPos = start + v.length + 2;
+                        input.setSelectionRange(newPos, newPos);
+                      });
+                    } else {
+                      setOutputTemplate((prev) => prev + `{${v}}`);
+                    }
+                  }}
+                  style={{
+                    padding: '2px 8px',
+                    borderRadius: 'var(--radius-sm)',
+                    border: '1px solid var(--border)',
+                    backgroundColor: 'var(--bg-hover)',
+                    color: 'var(--text-secondary)',
+                    fontSize: 'var(--font-size-xs)',
+                    fontFamily: 'var(--font-mono, "SF Mono", "Fira Code", monospace)',
+                    cursor: 'pointer',
+                    transition: 'background-color var(--transition-fast)',
+                  }}
+                  title={`Insert {${v}} at cursor`}
+                >
+                  {`{${v}}`}
+                </button>
+              ))}
+            </div>
+          </div>
+
+          {/* Live preview */}
+          <div>
+            <span style={{ fontSize: 'var(--font-size-xs)', color: 'var(--text-muted)', marginBottom: 'var(--space-1)', display: 'block' }}>
+              Preview
+            </span>
+            <div
+              style={{
+                padding: 'var(--space-2) var(--space-3)',
+                borderRadius: 'var(--radius-md)',
+                backgroundColor: 'var(--bg-main)',
+                border: '1px solid var(--border)',
+                fontFamily: 'var(--font-mono, "SF Mono", "Fira Code", monospace)',
+                fontSize: 'var(--font-size-xs)',
+                color: 'var(--text-muted)',
+                wordBreak: 'break-all',
+              }}
+            >
+              {templatePreview || '—'}
+            </div>
+          </div>
+        </div>
+      </section>
+
       {/* ── Platform Settings section ── */}
       <section style={{ marginBottom: 'var(--space-8)' }}>
         <div style={{ marginBottom: 'var(--space-4)' }}>

src/server/routes/system.ts

@@ -14,6 +14,7 @@ import {
   setAppSetting,
   APP_CHECK_INTERVAL,
   APP_CONCURRENT_DOWNLOADS,
+  APP_OUTPUT_TEMPLATE,
   YTDLP_LAST_UPDATED,
 } from '../../db/repositories/system-config-repository';
 import { getYtDlpVersion, updateYtDlp } from '../../sources/yt-dlp';
@@ -114,11 +115,12 @@ export async function systemRoutes(fastify: FastifyInstance): Promise<void> {
    */
   fastify.get('/api/v1/system/settings', async (_request, _reply) => {
     const db = fastify.db;
-    const settings = await getAppSettings(db, [APP_CHECK_INTERVAL, APP_CONCURRENT_DOWNLOADS]);
+    const settings = await getAppSettings(db, [APP_CHECK_INTERVAL, APP_CONCURRENT_DOWNLOADS, APP_OUTPUT_TEMPLATE]);
 
     const response: AppSettingsResponse = {
       checkInterval: parseInt(settings[APP_CHECK_INTERVAL] ?? '360', 10),
       concurrentDownloads: parseInt(settings[APP_CONCURRENT_DOWNLOADS] ?? '2', 10),
+      outputTemplate: settings[APP_OUTPUT_TEMPLATE] ?? '{platform}/{channel}/{title}.{ext}',
     };
 
     return response;
@@ -131,7 +133,7 @@ export async function systemRoutes(fastify: FastifyInstance): Promise<void> {
    */
   fastify.put('/api/v1/system/settings', async (request, reply) => {
     const db = fastify.db;
-    const body = request.body as { checkInterval?: number; concurrentDownloads?: number };
+    const body = request.body as { checkInterval?: number; concurrentDownloads?: number; outputTemplate?: string };
 
     // Validate
     if (body.checkInterval !== undefined) {
@@ -172,12 +174,30 @@ export async function systemRoutes(fastify: FastifyInstance): Promise<void> {
         fastify.queueService.setConcurrency(body.concurrentDownloads);
       }
     }
+    if (body.outputTemplate !== undefined) {
+      if (typeof body.outputTemplate !== 'string' || body.outputTemplate.trim().length === 0) {
+        return reply.status(400).send({
+          statusCode: 400,
+          error: 'Bad Request',
+          message: 'outputTemplate must be a non-empty string',
+        });
+      }
+      if (!body.outputTemplate.includes('{ext}')) {
+        return reply.status(400).send({
+          statusCode: 400,
+          error: 'Bad Request',
+          message: 'outputTemplate must contain {ext} for the file extension',
+        });
+      }
+      await setAppSetting(db, APP_OUTPUT_TEMPLATE, body.outputTemplate);
+    }
 
     // Return updated values
-    const settings = await getAppSettings(db, [APP_CHECK_INTERVAL, APP_CONCURRENT_DOWNLOADS]);
+    const settings = await getAppSettings(db, [APP_CHECK_INTERVAL, APP_CONCURRENT_DOWNLOADS, APP_OUTPUT_TEMPLATE]);
     const response: AppSettingsResponse = {
       checkInterval: parseInt(settings[APP_CHECK_INTERVAL] ?? '360', 10),
       concurrentDownloads: parseInt(settings[APP_CONCURRENT_DOWNLOADS] ?? '2', 10),
+      outputTemplate: settings[APP_OUTPUT_TEMPLATE] ?? '{platform}/{channel}/{title}.{ext}',
     };
 
     return response;

src/types/api.ts

@@ -74,6 +74,7 @@ export interface ContentCounts {
 export interface AppSettingsResponse {
   checkInterval: number;
   concurrentDownloads: number;
+  outputTemplate: string;
 }
 
 /** Channel with aggregated content counts — returned by GET /api/v1/channel. */