specrails-desktop 2.8.0 → 2.9.1

package/server/dist/docs-router.js

@@ -8,68 +8,116 @@ const express_1 = require("express");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
-// ─── Docs directory resolution ────────────────────────────────────────────────
-// Try ~/.specrails/docs/ first (user-editable), then fall back to bundled docs/
-function resolveDocsDir() {
-    const userDocsDir = path_1.default.join(os_1.default.homedir(), '.specrails', 'docs');
-    if (fs_1.default.existsSync(userDocsDir)) {
-        return userDocsDir;
+// ─── User-guide docs ────────────────────────────────────────────────────────
+//
+// The Documentation panel serves a dedicated, language-aware USER-GUIDE tree —
+// NOT the developer docs (docs/internals, docs/platforms, top-level dev .md).
+// Layout on disk:
+//
+//   docs/guide/<lang>/<category>/<order>-<slug>.md
+//
+// where <lang> is an i18n language id (`en`, `es`, …). English (`en`) is the
+// source-of-truth locale and is always present; any missing language OR missing
+// page falls back to the English file, so an untranslated language still shows
+// real content instead of an empty panel.
+//
+// Resolution precedence for the guide ROOT (the dir that holds <lang>/):
+//   1. ~/.specrails/docs/guide/   (user-editable override — wins when present)
+//   2. bundled Tauri resource     (<resource_dir>/docs/guide in the packaged app)
+//   3. repo / compiled dist       (docs/guide relative to __dirname)
+// All candidates are existence-gated; a missing tree never crashes — the panel
+// just shows no categories.
+// ─── Default language + validation ──────────────────────────────────────────
+const DEFAULT_LANG = 'en';
+// Mirror of client/src/lib/i18n.ts LANGUAGE_IDS. Kept here (not imported — the
+// server is CommonJS and must not depend on the ESM client) so an unknown / bogus
+// `?lang=` value can never be turned into a filesystem path.
+const SUPPORTED_LANGS = new Set(['en', 'es', 'fr', 'de', 'pt', 'it', 'zh', 'ja']);
+function normalizeLang(raw) {
+    if (typeof raw !== 'string')
+        return DEFAULT_LANG;
+    const base = raw.toLowerCase().split('-')[0].trim();
+    return SUPPORTED_LANGS.has(base) ? base : DEFAULT_LANG;
+}
+// ─── Guide-root resolution ──────────────────────────────────────────────────
+/**
+ * The bundled (packaged-app) guide root, or null when not running inside a
+ * Tauri bundle / the dir is absent. The Tauri host exports
+ * `SPECRAILS_BUNDLED_DOCS_PATH=<resource_dir>/docs` (existence-gated, mirroring
+ * the runtimes/core envs); as a defence-in-depth fallback we also derive
+ * `<resource_dir>/docs` from `SPECRAILS_BUNDLED_RUNTIMES_PATH` (whose parent IS
+ * the resource dir) so a build that forgot the docs env still resolves.
+ */
+function resolveBundledGuideRoot() {
+    const direct = process.env.SPECRAILS_BUNDLED_DOCS_PATH;
+    if (direct && direct.length > 0) {
+        const guide = path_1.default.join(direct, 'guide');
+        if (fs_1.default.existsSync(guide))
+            return guide;
     }
-    // Bundled docs: try relative to this file (works in dev and compiled)
+    const runtimes = process.env.SPECRAILS_BUNDLED_RUNTIMES_PATH;
+    if (runtimes && runtimes.length > 0) {
+        // <resource_dir>/runtimes → <resource_dir>/docs/guide
+        const guide = path_1.default.join(path_1.default.dirname(runtimes), 'docs', 'guide');
+        if (fs_1.default.existsSync(guide))
+            return guide;
+    }
+    return null;
+}
+/**
+ * Resolve the guide ROOT directory (the one containing <lang>/ subdirs).
+ * Returns null when no guide tree can be found anywhere (the panel then shows
+ * an empty index rather than crashing).
+ */
+function resolveGuideRoot() {
+    // 1. User override: ~/.specrails/docs/guide
+    const userGuide = path_1.default.join(os_1.default.homedir(), '.specrails', 'docs', 'guide');
+    if (fs_1.default.existsSync(userGuide))
+        return userGuide;
+    // 2. Bundled app resource
+    const bundled = resolveBundledGuideRoot();
+    if (bundled)
+        return bundled;
+    // 3. Repo / compiled dist (relative to this file)
     const candidates = [
-        path_1.default.resolve(__dirname, '../docs'), // dev: server/ -> ../docs
-        path_1.default.resolve(__dirname, '../../docs'), // compiled: server/dist/ -> ../../docs
+        path_1.default.resolve(__dirname, '../docs/guide'), // dev: server/ -> ../docs/guide
+        path_1.default.resolve(__dirname, '../../docs/guide'), // compiled: server/dist/ -> ../../docs/guide
     ];
     for (const candidate of candidates) {
-        if (fs_1.default.existsSync(candidate)) {
+        if (fs_1.default.existsSync(candidate))
             return candidate;
-        }
     }
-    // Fall back to user dir (will be empty until populated)
-    return userDocsDir;
+    return null;
 }
-// ─── Category configuration ───────────────────────────────────────────────────
-/**
- * Top-level `.md` files are surfaced under a synthetic "guides" category.
- * Any subdirectory becomes its own category, with the directory name as slug
- * and a friendly label resolved from `CATEGORY_LABELS` (or title-cased).
- */
-const TOP_LEVEL_CATEGORY_SLUG = 'guides';
+/** The localized directory for a given language under the guide root. */
+function langDir(guideRoot, lang) {
+    return path_1.default.join(guideRoot, lang);
+}
+// ─── Category configuration ─────────────────────────────────────────────────
 const CATEGORY_LABELS = {
-    guides: 'Guides',
-    platforms: 'Platforms',
-    internals: 'Internals',
-    // Legacy folders (kept so user-customized ~/.specrails/docs trees still work)
-    general: 'General',
-    product: 'Product',
-    engineering: 'Engineering',
-    operations: 'Operations',
+    'getting-started': 'Getting started',
+    specs: 'Specs',
+    pipeline: 'Pipeline',
+    agents: 'Agents',
+    insights: 'Insights',
+    integrations: 'Integrations',
+    settings: 'Settings',
 };
 /**
- * Preferred display order. Categories not in this list come after, in the
- * order `fs.readdirSync` returns them.
- */
-const CATEGORY_ORDER = ['guides', 'platforms', 'internals', 'general', 'product', 'engineering', 'operations'];
-/**
- * Preferred document order within the "guides" category. Files not listed
- * here are appended in alphabetical order so adding a new doc never breaks
- * the build.
+ * Preferred display order. Categories not in this list come after, alphabetically.
  */
-const GUIDES_DOC_ORDER = [
+const CATEGORY_ORDER = [
     'getting-started',
-    'creating-specs',
-    'running-pipelines',
-    'tracking-cost',
-    'customizing',
-    'terminal',
-    'cli',
-    'codex',
+    'specs',
+    'pipeline',
+    'agents',
+    'insights',
+    'integrations',
+    'settings',
 ];
-// ─── Helpers ──────────────────────────────────────────────────────────────────
+// ─── Helpers ────────────────────────────────────────────────────────────────
 function slugToTitle(slug) {
-    return slug
-        .replace(/-/g, ' ')
-        .replace(/\b\w/g, (c) => c.toUpperCase());
+    return slug.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
 }
 function categoryLabel(slug) {
     return CATEGORY_LABELS[slug] ?? slugToTitle(slug);
@@ -78,130 +126,160 @@ function extractTitle(content, slug) {
     const match = content.match(/^#\s+(.+)$/m);
     return match ? match[1].trim() : slugToTitle(slug);
 }
-function sortBy(items, preferredOrder, keyFn) {
-    const preferredIndex = (key) => {
-        const i = preferredOrder.indexOf(key);
-        return i === -1 ? Number.MAX_SAFE_INTEGER : i;
-    };
-    return [...items].sort((a, b) => {
-        const aKey = keyFn(a);
-        const bKey = keyFn(b);
-        const ai = preferredIndex(aKey);
-        const bi = preferredIndex(bKey);
-        if (ai !== bi)
-            return ai - bi;
-        return aKey.localeCompare(bKey);
-    });
+/** Parse an `<order>-<slug>.md` filename into { order, slug }. */
+function parseGuideFile(file) {
+    const m = file.match(/^(\d+)-(.+)\.md$/);
+    if (!m)
+        return null;
+    return { order: parseInt(m[1], 10), slug: m[2] };
 }
-function readMarkdownFiles(dir) {
-    try {
-        return fs_1.default.readdirSync(dir).filter((f) => f.endsWith('.md') && f.toLowerCase() !== 'readme.md');
-    }
-    catch {
-        return [];
-    }
+function categoryRank(slug) {
+    const i = CATEGORY_ORDER.indexOf(slug);
+    return i === -1 ? Number.MAX_SAFE_INTEGER : i;
 }
-function readDocEntry(file, filePath) {
-    const slug = file.replace(/\.md$/, '');
+/** List the category subdirectories of a localized lang dir (existence-safe). */
+function listCategories(dir) {
     try {
-        const content = fs_1.default.readFileSync(filePath, 'utf-8');
-        return { title: extractTitle(content, slug), slug };
+        return fs_1.default
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
     }
     catch {
-        return { title: slugToTitle(slug), slug };
+        return [];
     }
 }
-function buildCategories(docsDir) {
-    if (!fs_1.default.existsSync(docsDir))
+/**
+ * Build the full category/doc index for a language, falling back to English
+ * per-category and per-page. The English tree defines the canonical set of
+ * categories and slugs; a translated language contributes localized titles for
+ * the pages it has, and English fills the gaps.
+ */
+function buildCategories(guideRoot, lang) {
+    const enDir = langDir(guideRoot, DEFAULT_LANG);
+    if (!fs_1.default.existsSync(enDir))
         return [];
+    const localizedDir = langDir(guideRoot, lang);
     const categories = [];
-    // 1. Top-level .md files → "guides" category
-    const topFiles = readMarkdownFiles(docsDir);
-    if (topFiles.length > 0) {
-        const docs = topFiles.map((f) => readDocEntry(f, path_1.default.join(docsDir, f)));
-        const ordered = sortBy(docs, GUIDES_DOC_ORDER, (d) => d.slug);
-        categories.push({ name: categoryLabel(TOP_LEVEL_CATEGORY_SLUG), slug: TOP_LEVEL_CATEGORY_SLUG, docs: ordered });
+    for (const cat of listCategories(enDir)) {
+        const enCatDir = path_1.default.join(enDir, cat);
+        const localizedCatDir = path_1.default.join(localizedDir, cat);
+        let files;
+        try {
+            files = fs_1.default.readdirSync(enCatDir).filter((f) => f.endsWith('.md'));
+        }
+        catch {
+            files = [];
+        }
+        const parsed = files
+            .map((f) => ({ file: f, meta: parseGuideFile(f) }))
+            .filter((x) => x.meta !== null)
+            .sort((a, b) => a.meta.order - b.meta.order || a.meta.slug.localeCompare(b.meta.slug));
+        const docs = parsed.map(({ file, meta }) => {
+            // Prefer the localized file's title; fall back to the English file.
+            const localizedPath = path_1.default.join(localizedCatDir, file);
+            const enPath = path_1.default.join(enCatDir, file);
+            const readPath = fs_1.default.existsSync(localizedPath) ? localizedPath : enPath;
+            let title = slugToTitle(meta.slug);
+            try {
+                title = extractTitle(fs_1.default.readFileSync(readPath, 'utf-8'), meta.slug);
+            }
+            catch {
+                /* fall back to slug-derived title */
+            }
+            return { title, slug: meta.slug };
+        });
+        if (docs.length > 0) {
+            categories.push({ name: categoryLabel(cat), slug: cat, docs });
+        }
     }
-    // 2. Each subdirectory → its own category
-    let entries;
+    return categories.sort((a, b) => categoryRank(a.slug) - categoryRank(b.slug) || a.slug.localeCompare(b.slug));
+}
+// ─── Path-safety guards ─────────────────────────────────────────────────────
+function isSafeSegment(seg) {
+    return (typeof seg === 'string' &&
+        seg.length > 0 &&
+        seg !== '.' &&
+        seg !== '..' &&
+        seg === path_1.default.basename(seg) &&
+        !seg.includes('/') &&
+        !seg.includes('\\'));
+}
+/**
+ * Resolve the on-disk file for a (lang, category, slug). Tries the localized
+ * file first, then English. Returns null when neither exists or a path-safety
+ * check fails. The slug in the URL is the *bare* slug (no order prefix); we map
+ * it to the `<order>-<slug>.md` file by scanning the English category dir
+ * (English is canonical for the set of slugs).
+ */
+function resolveDocFile(guideRoot, lang, category, slug) {
+    if (!isSafeSegment(category) || !isSafeSegment(slug))
+        return null;
+    const enCatDir = path_1.default.join(langDir(guideRoot, DEFAULT_LANG), category);
+    let files;
     try {
-        entries = fs_1.default.readdirSync(docsDir, { withFileTypes: true });
+        files = fs_1.default.readdirSync(enCatDir).filter((f) => f.endsWith('.md'));
     }
     catch {
-        entries = [];
-    }
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        // Avoid colliding with synthetic top-level slug
-        if (entry.name === TOP_LEVEL_CATEGORY_SLUG)
-            continue;
-        const catDir = path_1.default.join(docsDir, entry.name);
-        const files = readMarkdownFiles(catDir);
-        const docs = files.map((f) => readDocEntry(f, path_1.default.join(catDir, f)));
-        // Sort docs within unknown categories alphabetically.
-        docs.sort((a, b) => a.slug.localeCompare(b.slug));
-        categories.push({ name: categoryLabel(entry.name), slug: entry.name, docs });
+        return null;
     }
-    return sortBy(categories, CATEGORY_ORDER, (c) => c.slug);
-}
-function isValidCategorySlug(cat) {
-    // basename(cat) === cat guards against slashes, but `path.basename('..') === '..'`,
-    // so '.'/'..' slip through and `path.join(docsDir, '..', ...)` escapes one level
-    // up (B4). Reject the dot segments explicitly.
-    return (cat.length > 0 &&
-        cat !== '.' &&
-        cat !== '..' &&
-        cat === path_1.default.basename(cat) &&
-        !cat.includes('/') &&
-        !cat.includes('\\'));
+    const match = files.find((f) => {
+        const meta = parseGuideFile(f);
+        return meta?.slug === slug;
+    });
+    if (!match)
+        return null;
+    const localizedPath = path_1.default.join(langDir(guideRoot, lang), category, match);
+    const enPath = path_1.default.join(enCatDir, match);
+    const filePath = fs_1.default.existsSync(localizedPath) ? localizedPath : enPath;
+    // Defence-in-depth: the resolved file must live inside the guide root.
+    const rel = path_1.default.relative(path_1.default.resolve(guideRoot), path_1.default.resolve(filePath));
+    if (rel.startsWith('..') || path_1.default.isAbsolute(rel))
+        return null;
+    if (!fs_1.default.existsSync(filePath))
+        return null;
+    return { filePath };
 }
-// ─── Router ───────────────────────────────────────────────────────────────────
+// ─── Router ─────────────────────────────────────────────────────────────────
 function createDocsRouter() {
     const router = (0, express_1.Router)();
-    router.get('/', (_req, res) => {
-        const docsDir = resolveDocsDir();
-        const categories = buildCategories(docsDir);
+    router.get('/', (req, res) => {
+        const lang = normalizeLang(req.query.lang);
+        const guideRoot = resolveGuideRoot();
+        const categories = guideRoot ? buildCategories(guideRoot, lang) : [];
         res.json({ categories });
     });
     router.get('/:category/:slug', (req, res) => {
         const { category, slug } = req.params;
-        if (!isValidCategorySlug(category)) {
+        const lang = normalizeLang(req.query.lang);
+        if (!isSafeSegment(category)) {
             res.status(404).json({ error: 'Category not found' });
             return;
         }
-        // Prevent directory traversal in slug too
-        const safeSlug = path_1.default.basename(slug);
-        if (safeSlug !== slug || slug.includes('/') || slug.includes('\\')) {
+        if (!isSafeSegment(slug)) {
             res.status(400).json({ error: 'Invalid slug' });
             return;
         }
-        const docsDir = resolveDocsDir();
-        // For the synthetic "guides" category, files live at the top level of docsDir.
-        const filePath = category === TOP_LEVEL_CATEGORY_SLUG
-            ? path_1.default.join(docsDir, `${safeSlug}.md`)
-            : path_1.default.join(docsDir, category, `${safeSlug}.md`);
-        // B4: defence-in-depth — never serve a file resolved outside docsDir, even
-        // if a future change loosens the slug/category validation above.
-        const rel = path_1.default.relative(path_1.default.resolve(docsDir), path_1.default.resolve(filePath));
-        if (rel.startsWith('..') || path_1.default.isAbsolute(rel)) {
+        const guideRoot = resolveGuideRoot();
+        if (!guideRoot) {
             res.status(404).json({ error: 'Document not found' });
             return;
         }
-        if (!fs_1.default.existsSync(filePath)) {
+        const resolved = resolveDocFile(guideRoot, lang, category, slug);
+        if (!resolved) {
             res.status(404).json({ error: 'Document not found' });
             return;
         }
         let content;
         try {
-            content = fs_1.default.readFileSync(filePath, 'utf-8');
+            content = fs_1.default.readFileSync(resolved.filePath, 'utf-8');
         }
         catch {
             res.status(500).json({ error: 'Failed to read document' });
             return;
         }
-        const title = extractTitle(content, safeSlug);
-        res.json({ title, content, category, slug: safeSlug });
+        const title = extractTitle(content, slug);
+        res.json({ title, content, category, slug });
     });
     return router;
 }

package/server/dist/file-summary-manager.js

@@ -95,20 +95,23 @@ function readSummary(projectPath, relPath) {
         return null;
     }
 }
-function writeSummary(projectPath, relPath, payload) {
-    const dir = summariesDir(projectPath);
+function writeSummary(summaryRoot, relPath, payload, 
+/** When false (relocated: summaryRoot is the app-owned workspace), skip the
+ *  `.gitignore` append — the workspace `.gitignore` is not the user's repo. */
+appendGitignore = true) {
+    const dir = summariesDir(summaryRoot);
     const firstWrite = !fs.existsSync(dir);
     fs.mkdirSync(dir, { recursive: true });
-    const final = summaryFilePath(projectPath, relPath);
+    const final = summaryFilePath(summaryRoot, relPath);
     // Atomic write: temp file in the same directory, then rename.
     const tmp = `${final}.tmp.${(0, crypto_1.randomBytes)(6).toString('hex')}`;
     fs.writeFileSync(tmp, JSON.stringify(payload), { encoding: 'utf8', mode: 0o600 });
     fs.renameSync(tmp, final);
-    if (firstWrite) {
+    if (firstWrite && appendGitignore) {
         // The app appends `.specrails/file-summaries/` to the project `.gitignore`
         // on first write. Idempotent: only appends when the line is absent.
         try {
-            ensureGitignoreLine(projectPath, '.specrails/file-summaries/');
+            ensureGitignoreLine(summaryRoot, '.specrails/file-summaries/');
         }
         catch { /* non-fatal */ }
     }
@@ -130,8 +133,13 @@ function ensureGitignoreLine(projectPath, line) {
     fs.writeFileSync(gi, `${existing}${sep}${line}\n`, 'utf8');
     return true;
 }
-function sweepOrphans(projectPath, cap = 200) {
-    const dir = summariesDir(projectPath);
+function sweepOrphans(summaryRoot, cap = 200, 
+/** Where to resolve source files (the repo). Relocate-artifacts: summaries
+ *  live under `summaryRoot` (workspace) but source is under `sourceRoot`
+ *  (repo). Defaults to `summaryRoot` (legacy, byte-identical). */
+sourceRoot) {
+    const dir = summariesDir(summaryRoot);
+    const srcRoot = sourceRoot ?? summaryRoot;
     let deleted = 0;
     let remaining = 0;
     let entries;
@@ -154,7 +162,7 @@ function sweepOrphans(projectPath, cap = 200) {
         catch {
             continue;
         }
-        const sourceAbs = path.join(projectPath, payload.path);
+        const sourceAbs = path.join(srcRoot, payload.path);
         if (fs.existsSync(sourceAbs))
             continue;
         if (deleted >= cap) {
@@ -266,7 +274,8 @@ class FileSummaryManager {
         // summaries; without `force` an explicit "Regenerate" of an unchanged file
         // would be a silent no-op.
         const currentLang = this.deps.language?.() ?? 'en';
-        const existing = readSummary(req.projectPath, req.relPath);
+        const summaryRoot = req.summaryRoot ?? req.projectPath;
+        const existing = readSummary(summaryRoot, req.relPath);
         if (!req.force &&
             existing &&
             existing.fileHash === newHash &&
@@ -442,7 +451,11 @@ class FileSummaryManager {
                 generatedBy: { model: out.model, promptVersion: CURRENT_PROMPT_VERSION, truncated },
                 triggeredBy: req.triggeredBy,
             };
-            writeSummary(req.projectPath, req.relPath, payload);
+            // Relocate-artifacts: summaries OUTPUT to the workspace when relocated
+            // (summaryRoot ≠ projectPath ⇒ skip the repo .gitignore append); source
+            // was read above from req.projectPath (the repo). Legacy ⇒ both equal.
+            const summaryRoot = req.summaryRoot ?? req.projectPath;
+            writeSummary(summaryRoot, req.relPath, payload, summaryRoot === req.projectPath);
             // Keep the watcher's negative-cache a correct superset.
             this.knownSummaries.get(req.projectId)?.add(req.relPath);
             try {
@@ -531,22 +544,34 @@ class FileSummaryManager {
             this.activeControllers.delete(controller);
         }
     }
-    markStale(projectPath, projectId, relPath) {
-        const existing = readSummary(projectPath, relPath);
+    /** `summaryRoot` (relocate-artifacts) is where the summary JSON lives — the
+     *  workspace when relocated, else === projectPath. */
+    markStale(projectPath, projectId, relPath, summaryRoot) {
+        const existing = readSummary(summaryRoot ?? projectPath, relPath);
         if (!existing)
             return;
         this.deps.broadcast(buildSummaryUpdated(projectId, existing, true));
     }
-    attachWatcher(projectId, projectPath) {
+    /**
+     * Watch the repo SOURCE tree (`projectPath`) for edits and mark the
+     * corresponding summary stale. Relocate-artifacts: `summaryRoot` is where the
+     * summary JSON lives (workspace when relocated) — source is watched at
+     * `projectPath`, summaries are scanned/swept/marked at `summaryRoot`. When
+     * omitted `summaryRoot` defaults to `projectPath` (legacy, byte-identical).
+     */
+    attachWatcher(projectId, projectPath, summaryRoot) {
         if (this.watchers.has(projectId))
             return;
-        this.knownSummaries.set(projectId, this.scanKnownSummaries(projectPath));
+        const sumRoot = summaryRoot ?? projectPath;
+        this.knownSummaries.set(projectId, this.scanKnownSummaries(sumRoot));
         // Reclaim summary JSON files whose source file was renamed/deleted since the
         // last session. Runs once per project per session (attachWatcher is
         // idempotent) and is capped at 200/pass inside sweepOrphans. The chokidar
         // watcher only sees 'change', never 'unlink', so this is the only reaper.
+        // sweepOrphans resolves source files against the repo, so it must know both:
+        // summaries under sumRoot, source under projectPath.
         try {
-            sweepOrphans(projectPath);
+            sweepOrphans(sumRoot, undefined, projectPath);
         }
         catch { /* best effort */ }
         // CRITICAL: prune build/dep trees (node_modules, dist, target, src-tauri/target,
@@ -574,7 +599,7 @@ class FileSummaryManager {
             const known = this.knownSummaries.get(projectId);
             if (known && !known.has(rel))
                 return;
-            this.markStale(projectPath, projectId, rel);
+            this.markStale(projectPath, projectId, rel, sumRoot);
         });
         this.watchers.set(projectId, { projectPath, watcher });
     }