pbakaus/impeccable · warning

Not found

Error message

Not found

What it means

/design-system/raw serves the project's DESIGN.md verbatim and returns 404 'Not found' when statOrNull(mdPath) is null, i.e. no DESIGN.md exists at the path resolveProjectContext() resolved. Unlike /design-system.json, which answers {present:false} for the same state, the raw endpoint has no JSON fallback shape.

Source

Thrown at skill/scripts/live-server.mjs:892

    //                              mdNewerThanJson, parseError?, sidecarError? }
    //                          - parsed: output of parseDesignMd (frontmatter
    //                            + the canonical sections) when DESIGN.md exists.
    //                          - sidecar: .impeccable/design.json contents when present.
    //                            Expected shape: schemaVersion 2, carrying
    //                            extensions + components + narrative.
    //   /design-system/raw     returns DESIGN.md markdown verbatim
    if (p === '/design-system.json' || p === '/design-system/raw') {
      const token = url.searchParams.get('token');
      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }

      const projectContext = resolveProjectContext();
      const mdPath = projectContext.resolvedDesignPath;
      const jsonPath = resolveDesignSidecarPath(process.cwd(), projectContext.designContextDir || projectContext.contextDir) || getDesignSidecarPath(process.cwd());
      const mdStat = statOrNull(mdPath);
      const jsonStat = statOrNull(jsonPath);

      if (p === '/design-system/raw') {
        if (!mdStat) { res.writeHead(404); res.end('Not found'); return; }
        res.writeHead(200, { 'Content-Type': 'text/markdown; charset=utf-8' });
        res.end(fs.readFileSync(mdPath, 'utf-8'));
        return;
      }

      if (!mdStat && !jsonStat) {
        res.writeHead(404, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify({ present: false }));
        return;
      }

      const response = {
        present: true,
        hasMd: !!mdStat,
        hasSidecar: !!jsonStat,
        mdNewerThanJson: !!(mdStat && jsonStat && mdStat.mtimeMs > jsonStat.mtimeMs + 1000),
      };

View on GitHub (pinned to f88b2837a7)

Solutions

  1. Run the design-system creation flow (skill scripts) so DESIGN.md is generated at the project root or context dir
  2. Use GET /design-system.json instead: it returns 200 {present:false, hasMd, hasSidecar} instead of a hard 404 when the file is absent
  3. Verify which path resolveProjectContext() resolved and place DESIGN.md there

Example fix

// before
const res = await fetch(`/design-system/raw?token=${t}`);
if (res.status === 404) throw new Error('raw design missing');

// after
const res = await fetch(`/design-system.json?token=${t}`);
const { present, hasMd } = await res.json();
if (!present) console.log('no design system yet');
Defensive patterns

Strategy: fallback

Validate before calling

import { statSync } from 'node:fs';
function hasDesignMd(resolvedDesignPath) {
  try { return statSync(resolvedDesignPath).isFile(); } catch { return false; }
}

Try / catch

const res = await fetch(`/design-system/raw?token=${t}`);
if (res.status === 404) { /* fall back to defaults or /design-system.json metadata */ }

Prevention

When it happens

Trigger: GET /design-system/raw on a project where the design system was never initialized (no DESIGN.md created by the design/extract flow), or where resolveProjectContext() resolved to a different context directory than the one holding the file.

Common situations: Running the panel/design tooling on a fresh repo before the skill has written a DESIGN.md; moving or renaming the context dir (.impeccable/) so the resolved design path no longer points at the file.

Related errors

AI-assisted analysis of pbakaus/impeccable@f88b2837a7 (2026-08-18). Data as JSON: /api/errors/7be4a0a087079421. Report an issue: GitHub.