@systemverification/styling-kit 2.0.0

package/src/bundle.js

@@ -0,0 +1,67 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import AdmZip from 'adm-zip';
+
+/**
+ * Unpack a private asset bundle zip into the target directories.
+ *
+ * Bundle layout:
+ *   manifest.json       — metadata + checksums (skipped, used for validation)
+ *   fonts.css           → stylesDir/fonts.css
+ *   fonts/*.woff2       → assetsDir/fonts/*.woff2
+ *   logo/logo.svg       → assetsDir/logo/logo.svg
+ *   favicon.png         → assetsDir/favicon.png
+ *
+ * @param {Buffer} zipBuffer
+ * @param {{ assetsDir: string, stylesDir: string }} destinations — absolute paths
+ * @returns {{ version: string }} manifest version
+ * @throws if any checksum fails or manifest is missing/invalid
+ */
+export function unpackBundle(zipBuffer, { assetsDir, stylesDir }) {
+  const zip = new AdmZip(zipBuffer);
+
+  const manifestEntry = zip.getEntry('manifest.json');
+  if (!manifestEntry) {
+    throw new Error('Asset bundle is missing manifest.json');
+  }
+
+  const manifest = JSON.parse(manifestEntry.getData().toString('utf8'));
+  if (!manifest.version || !manifest.checksums) {
+    throw new Error('Asset bundle manifest.json is malformed (missing version or checksums)');
+  }
+
+  // Validate checksums before writing anything
+  for (const [entryPath, expectedHash] of Object.entries(manifest.checksums)) {
+    const entry = zip.getEntry(entryPath);
+    if (!entry) {
+      throw new Error(`Bundle is missing file declared in manifest: ${entryPath}`);
+    }
+    const actualHash = crypto
+      .createHash('sha256')
+      .update(entry.getData())
+      .digest('hex');
+    if (actualHash !== expectedHash) {
+      throw new Error(`Checksum mismatch for ${entryPath}`);
+    }
+  }
+
+  // Write files after all checksums pass
+  for (const entry of zip.getEntries()) {
+    if (entry.isDirectory || entry.entryName === 'manifest.json') continue;
+
+    const entryName = entry.entryName;
+    let destPath;
+
+    if (entryName === 'fonts.css') {
+      destPath = path.join(stylesDir, 'fonts.css');
+    } else {
+      destPath = path.join(assetsDir, entryName);
+    }
+
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    fs.writeFileSync(destPath, entry.getData());
+  }
+
+  return { version: manifest.version };
+}

package/src/config.js

@@ -0,0 +1,67 @@
+import fs from 'fs';
+import path from 'path';
+
+export const CONFIG_FILE = 'sv-style.json';
+export const TOOL_VERSION = '2.0.0';
+export const BLOB_DEFAULTS = {
+  accountName: 'svstylingkit',
+  containerName: 'licensed-assets',
+};
+
+export function readConfig(cwd) {
+  const configPath = path.join(cwd, CONFIG_FILE);
+  return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+}
+
+export function writeConfig(cwd, config) {
+  const configPath = path.join(cwd, CONFIG_FILE);
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+}
+
+/**
+ * Build a fresh v2 config object for a new init.
+ */
+export function buildConfig({ stylesDir, assetsDir, docsDir, publicDir }) {
+  return {
+    svStyle: {
+      toolVersion: TOOL_VERSION,
+      assetsVersion: null,
+      installMode: 'degraded',
+      blob: { ...BLOB_DEFAULTS },
+      paths: {
+        tokens: `${stylesDir}/tokens-core.css`,
+        fonts: `${stylesDir}/fonts.css`,
+        assets: assetsDir,
+        docs: docsDir,
+        publicDir,
+      },
+    },
+  };
+}
+
+/**
+ * Migrate a v1 config (has svStyle.version) to v2 schema.
+ * Returns the config unchanged if it is already v2.
+ */
+export function migrateConfig(config) {
+  if (config.svStyle.toolVersion) return config;
+
+  const { paths } = config.svStyle;
+  const tokensDir = paths.tokens.replace(/\/[^/]+$/, '');
+
+  return {
+    svStyle: {
+      toolVersion: TOOL_VERSION,
+      assetsVersion: null,
+      installMode: 'unknown',
+      blob: { ...BLOB_DEFAULTS },
+      paths: {
+        tokens: `${tokensDir}/tokens-core.css`,
+        fonts: `${tokensDir}/fonts.css`,
+        assets: paths.assets,
+        docs: paths.docs,
+        publicDir: paths.publicDir || 'public',
+      },
+    },
+  };
+}

package/src/doctor.js

@@ -0,0 +1,113 @@
+import fs from 'fs';
+import path from 'path';
+import { DefaultAzureCredential } from '@azure/identity';
+import { BlobClient } from '@azure/storage-blob';
+import { CONFIG_FILE, BLOB_DEFAULTS } from './config.js';
+import { classifyBlobError } from './assets.js';
+
+const BUNDLE_BLOB_PATH = 'sv-style/assets/latest/asset-bundle.zip';
+
+async function checkBlobAccess(blobConfig) {
+  const { accountName, containerName } = blobConfig ?? BLOB_DEFAULTS;
+  const url = `https://${accountName}.blob.core.windows.net/${containerName}/${BUNDLE_BLOB_PATH}`;
+  try {
+    await new BlobClient(url, new DefaultAzureCredential()).getProperties();
+    return { ok: true, message: 'Azure Blob reachable and authenticated' };
+  } catch (err) {
+    const type = classifyBlobError(err);
+    return { ok: false, message: `Azure Blob: ${err.message} (${type})` };
+  }
+}
+
+export default async function doctor(_deps = {}) {
+  const cwd = _deps.cwd ?? process.cwd();
+  const checks = [];
+
+  const pass = (name, msg) => checks.push({ name, ok: true, message: msg });
+  const fail = (name, msg) => checks.push({ name, ok: false, message: msg });
+
+  // 1. Config file
+  const configPath = path.join(cwd, CONFIG_FILE);
+  let config = null;
+  if (!fs.existsSync(configPath)) {
+    fail('config', 'sv-style.json not found — run sv-style init');
+  } else {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      pass('config', 'sv-style.json present and valid JSON');
+    } catch (e) {
+      fail('config', `sv-style.json invalid JSON: ${e.message}`);
+    }
+  }
+
+  if (config) {
+    const s = config.svStyle;
+
+    // 2. Schema version
+    if (s?.toolVersion) {
+      pass('schema', `Tool version: v${s.toolVersion}`);
+    } else {
+      fail('schema', 'Old v1 config — run sv-style update to migrate');
+    }
+
+    // 3. Install mode
+    const mode = s?.installMode;
+    if (mode === 'full') {
+      pass('install-mode', `Install mode: full (assets v${s.assetsVersion})`);
+    } else if (mode === 'degraded') {
+      fail('install-mode', 'Install mode: degraded — branded assets not installed');
+    } else {
+      fail('install-mode', `Install mode: ${mode ?? 'unknown'} — run sv-style update`);
+    }
+
+    // 4. Public file paths
+    const pathChecks = [
+      { key: 'tokens', label: 'tokens-core.css' },
+      { key: 'fonts',  label: 'fonts.css' },
+      { key: 'docs',   label: 'docs directory', isDir: true },
+    ];
+
+    for (const { key, label, isDir } of pathChecks) {
+      const rel = s?.paths?.[key];
+      if (!rel) { fail(key, `${label}: path not configured`); continue; }
+      const abs = path.join(cwd, rel);
+      fs.existsSync(abs)
+        ? pass(key, `${label} → ${rel}`)
+        : fail(key, `${label} missing at ${rel}`);
+    }
+
+    // 5. Private binary assets
+    const assetsDir = s?.paths?.assets;
+    if (assetsDir) {
+      const present =
+        fs.existsSync(path.join(cwd, assetsDir, 'logo', 'logo.svg')) &&
+        fs.existsSync(path.join(cwd, assetsDir, 'favicon.png')) &&
+        fs.existsSync(path.join(cwd, assetsDir, 'fonts', 'body-font.woff2'));
+      present
+        ? pass('private-assets', `Private assets present in ${assetsDir}`)
+        : fail('private-assets', `Private assets missing in ${assetsDir} — run sv-style update after az login`);
+    } else {
+      fail('private-assets', 'assets path not configured');
+    }
+
+    // 6. Azure Blob access (live probe)
+    process.stdout.write('  Probing Azure Blob...\r');
+    const blobResult = await checkBlobAccess(s?.blob);
+    blobResult.ok
+      ? pass('blob-access', blobResult.message)
+      : fail('blob-access', blobResult.message);
+  }
+
+  // Print summary
+  const passed = checks.filter(c => c.ok).length;
+  console.log('\n── SV Style Doctor ──────────────────────────────────────');
+  for (const { ok, message } of checks) {
+    console.log(`  ${ok ? '✓' : '✗'}  ${message}`);
+  }
+  console.log('─────────────────────────────────────────────────────────');
+  console.log(`  ${passed}/${checks.length} checks passed`);
+  if (passed < checks.length) {
+    console.log(`  Tip: run 'sv-style update' (after 'az login' if needed)`);
+  }
+  console.log('');
+}

package/src/fs-utils.js

@@ -0,0 +1,15 @@
+import fs from 'fs';
+import path from 'path';
+
+export function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}

package/src/init.js

@@ -0,0 +1,182 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { copyDir } from './fs-utils.js';
+import { computeAssetUrlPrefix, rewriteFontPaths, rewriteDocAssetPaths } from './path-rewrite.js';
+import { CONFIG_FILE, buildConfig, writeConfig } from './config.js';
+import { downloadBundle } from './assets.js';
+import { unpackBundle } from './bundle.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const KIT_ROOT = path.resolve(__dirname, '..');
+
+const FALLBACK_FONTS_CSS = `/* SV Style System — Fallback Font Declarations (degraded mode)
+   Private licensed fonts are not installed. Using system fonts.
+   Run 'sv-style update' after authenticating with Azure to install branded fonts.
+   See 'sv-style doctor' for current status. */
+
+@font-face {
+  font-family: "BodyFont";
+  src: local("Segoe UI"), local("Helvetica Neue"), local("Arial");
+  font-weight: normal;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: "BodyFont";
+  src: local("Segoe UI"), local("Helvetica Neue"), local("Arial");
+  font-weight: normal;
+  font-style: italic;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: "HeadingFont";
+  src: local("Segoe UI"), local("Helvetica Neue"), local("Arial");
+  font-weight: normal;
+  font-style: normal;
+  font-display: swap;
+}
+`;
+
+function renderSnippet(template, { docsDir, tokensPath }) {
+  return template
+    .replace(/\{\{DOCS_DIR\}\}/g, docsDir)
+    .replace(/\{\{TOKENS_PATH\}\}/g, tokensPath);
+}
+
+export default async function init(flags, _deps = {}) {
+  const _downloadBundle = _deps.downloadBundle ?? downloadBundle;
+  const cwd = _deps.cwd ?? process.cwd();
+  const _exit = _deps.exit ?? ((code) => process.exit(code));
+  const requireAssets = flags.requireAssets ?? false;
+
+  if (fs.existsSync(path.join(cwd, CONFIG_FILE))) {
+    console.error(`sv-style.json already exists. Run 'update' to sync files.`);
+    return _exit(1);
+  }
+
+  const stylesDir = flags.stylesDir || 'src/styles/sv';
+  const assetsDir = flags.assetsDir || 'public/sv-assets';
+  const docsDir   = flags.docsDir   || 'docs/sv-style';
+  const publicDir = flags.publicDir || 'public';
+
+  const tokensPath = `${stylesDir}/tokens-core.css`;
+  const fontsPath  = `${stylesDir}/fonts.css`;
+  const assetUrlPrefix = computeAssetUrlPrefix(assetsDir, publicDir);
+
+  // Create destination directories
+  fs.mkdirSync(path.join(cwd, stylesDir), { recursive: true });
+  fs.mkdirSync(path.join(cwd, assetsDir), { recursive: true });
+  fs.mkdirSync(path.join(cwd, docsDir), { recursive: true });
+
+  // Install public files: tokens-core.css
+  fs.copyFileSync(
+    path.join(KIT_ROOT, 'tokens', 'tokens-core.css'),
+    path.join(cwd, tokensPath)
+  );
+
+  // Install docs (references to assets are rewritten to match the installed location)
+  copyDir(
+    path.join(KIT_ROOT, 'docs'),
+    path.join(cwd, docsDir)
+  );
+  rewriteDocAssetPaths(path.join(cwd, docsDir), assetUrlPrefix);
+
+  // Write initial config (installMode: degraded until assets confirmed)
+  const config = buildConfig({ stylesDir, assetsDir, docsDir, publicDir });
+  writeConfig(cwd, config);
+
+  // Patch AGENTS.md
+  const agentsPath = path.join(cwd, 'AGENTS.md');
+  const existingAgents = fs.existsSync(agentsPath)
+    ? fs.readFileSync(agentsPath, 'utf8')
+    : '';
+
+  if (existingAgents.includes('SV Style System')) {
+    console.log('AGENTS.md already contains SV Style section — skipping.');
+  } else {
+    const agentsTemplate = fs.readFileSync(
+      path.join(KIT_ROOT, 'templates', 'AGENTS_SNIPPET.md'),
+      'utf8'
+    );
+    const agentsSnippet = renderSnippet(agentsTemplate, { docsDir, tokensPath });
+    const agentsSeparator = existingAgents.endsWith('\n') ? '\n' : '\n\n';
+    fs.writeFileSync(agentsPath, existingAgents + agentsSeparator + agentsSnippet);
+    console.log(`Patched AGENTS.md`);
+  }
+
+  // Patch CLAUDE.md
+  const claudePath = path.join(cwd, 'CLAUDE.md');
+  const existingClaude = fs.existsSync(claudePath)
+    ? fs.readFileSync(claudePath, 'utf8')
+    : '';
+
+  if (existingClaude.includes('SV Style')) {
+    console.log('CLAUDE.md already contains SV Style section — skipping.');
+  } else {
+    const snippetTemplate = fs.readFileSync(
+      path.join(KIT_ROOT, 'templates', 'CLAUDE_SNIPPET.md'),
+      'utf8'
+    );
+    const snippet = renderSnippet(snippetTemplate, { docsDir, tokensPath });
+    const separator = existingClaude.endsWith('\n') ? '\n' : '\n\n';
+    fs.writeFileSync(claudePath, existingClaude + separator + snippet);
+    console.log(`Patched CLAUDE.md`);
+  }
+
+  // Attempt private asset download from Azure Blob
+  console.log(`\nDownloading private assets from Azure Blob...`);
+  try {
+    const zipBuffer = await _downloadBundle(config.svStyle.blob);
+    const { version: assetsVersion } = unpackBundle(zipBuffer, {
+      assetsDir: path.join(cwd, assetsDir),
+      stylesDir: path.join(cwd, stylesDir),
+    });
+    rewriteFontPaths(path.join(cwd, fontsPath), assetUrlPrefix);
+
+    config.svStyle.installMode = 'full';
+    config.svStyle.assetsVersion = assetsVersion;
+    writeConfig(cwd, config);
+
+    console.log(`
+SV Style System installed (full):
+  Tokens  → ${tokensPath}
+  Fonts   → ${fontsPath}
+  Assets  → ${assetsDir}/
+  Docs    → ${docsDir}/
+  Config  → ${CONFIG_FILE}
+  Agents  → AGENTS.md, CLAUDE.md
+`);
+  } catch (err) {
+    if (requireAssets) {
+      console.error(`\nAsset download failed (--require-assets): ${err.message}`);
+      return _exit(1);
+    }
+
+    // Degraded mode: write system font fallback
+    fs.writeFileSync(path.join(cwd, fontsPath), FALLBACK_FONTS_CSS);
+
+    console.warn(`
+⚠  Asset download failed — installed in degraded mode.
+   Reason: ${err.message}
+   Missing: branded fonts, logo, favicon.
+
+   To complete installation:
+     1. Authenticate: az login
+     2. Retry:        sv-style update
+
+   Run 'sv-style doctor' for full status.
+`);
+
+    console.log(`
+SV Style System installed (degraded):
+  Tokens  → ${tokensPath}
+  Fonts   → ${fontsPath}  (system font fallback)
+  Docs    → ${docsDir}/
+  Config  → ${CONFIG_FILE}
+  Agents  → AGENTS.md, CLAUDE.md
+`);
+  }
+}

package/src/login.js

@@ -0,0 +1,65 @@
+import fs from 'fs';
+import path from 'path';
+import { DefaultAzureCredential } from '@azure/identity';
+import { BlobClient } from '@azure/storage-blob';
+import { CONFIG_FILE, BLOB_DEFAULTS } from './config.js';
+import { classifyBlobError } from './assets.js';
+
+const BUNDLE_BLOB_PATH = 'sv-style/assets/latest/asset-bundle.zip';
+
+/**
+ * Test Azure Blob connectivity using the current credential chain.
+ * Reads blob config from sv-style.json if present, otherwise uses defaults.
+ */
+export default async function login(_deps = {}) {
+  const cwd = _deps.cwd ?? process.cwd();
+
+  let blobConfig = { ...BLOB_DEFAULTS };
+  const configPath = path.join(cwd, CONFIG_FILE);
+  if (fs.existsSync(configPath)) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (raw.svStyle?.blob) {
+        blobConfig = { ...blobConfig, ...raw.svStyle.blob };
+      }
+    } catch {}
+  }
+
+  const { accountName, containerName } = blobConfig;
+  const url = `https://${accountName}.blob.core.windows.net/${containerName}/${BUNDLE_BLOB_PATH}`;
+
+  console.log(`SV Style — Azure Blob access check`);
+  console.log(`  Account:   ${accountName}.blob.core.windows.net`);
+  console.log(`  Container: ${containerName}`);
+  console.log(`  Bundle:    ${BUNDLE_BLOB_PATH}`);
+
+  const credential = new DefaultAzureCredential();
+  const client = new BlobClient(url, credential);
+
+  try {
+    const props = await client.getProperties();
+    console.log(`\n✓  Access verified.`);
+    console.log(`   Bundle size: ${props.contentLength?.toLocaleString() ?? '?'} bytes`);
+    return true;
+  } catch (err) {
+    const type = classifyBlobError(err);
+    console.error(`\n✗  Access failed (${type}): ${err.message}`);
+    switch (type) {
+      case 'not-logged-in':
+        console.error(`   → Not logged in. Run: az login`);
+        break;
+      case 'unauthorized':
+        console.error(`   → No access. Contact your administrator to request access.`);
+        break;
+      case 'not-found':
+        console.error(`   → Bundle not found. Check accountName/containerName in sv-style.json.`);
+        break;
+      case 'network-error':
+        console.error(`   → Network error. Check your internet connection.`);
+        break;
+      default:
+        console.error(`   → Unexpected error. Try again or run 'sv-style doctor'.`);
+    }
+    return false;
+  }
+}