@reqvire-org/ads 0.0.0-stage → 0.2.9

package/dist/cli.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { checkProject, generateBrandAssets, generateLintConfig, initProject, inspectTokens } from "./index.mjs";
+
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const help = `ADS ${pkg.version} — tooling for a project's local design system
+
+Usage: ads init [options]           Run inside your project
+       ads <command> [directory] [--json]
+
+  init                 Set up ADS in the current project (requires package.json)
+  check [directory]    Check tokens, ownership, imports, and showcase coverage
+  tokens [directory]   Inspect local token values and theme definitions
+  assets [directory]   Generate standard web icons in .ds/assets from assets.iconSource
+  lint-config [dir]    Generate .ds/oxlintrc.json with core and project plugins
+  mcp [directory]      Serve stdio MCP tools/Apps and the local showcase website
+  showcase [directory] Serve the built-in MCP client website (no stdio connection)
+
+  --help              Show this help
+  --version           Show the tool version
+  --framework name     Init only: react or preact (required until saved in config)
+  --tool-package spec  Init only: tool version or local tarball for devDependency
+  --package-manager pm Init only: npm or bun (auto-detected from the project)
+  --port number        MCP/showcase only: loopback website port (default: automatic)
+  --no-showcase        MCP only: disable the local website
+  --mutations          MCP only: enable guarded ADS source editing
+
+External components and examples are imported using the ADS skills.
+No component library or example catalogue is bundled.
+`;
+
+async function main(args) {
+  if (!args.length || args.includes("--help")) { process.stdout.write(help); return; }
+  if (args.length === 1 && args[0] === "--version") { console.log(pkg.version); return; }
+  let json = false;
+  let toolPackage;
+  let packageManager;
+  let framework;
+  let port;
+  let showcase = true;
+  let mutations = false;
+  const positional = [];
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index];
+    if (argument === "--json") json = true;
+    else if (argument === "--no-showcase") showcase = false;
+    else if (argument === "--mutations") mutations = true;
+    else if (argument === "--port") {
+      const value = args[++index];
+      if (port !== undefined || !/^\d+$/.test(value ?? "") || Number(value) > 65535) throw new Error("--port requires one port between 0 and 65535.");
+      port = Number(value);
+    }
+    else if (argument === "--tool-package") {
+      if (toolPackage !== undefined || !args[index + 1] || args[index + 1].startsWith("-")) throw new Error("Specify one tool version or local tarball after --tool-package.");
+      toolPackage = args[++index];
+    } else if (argument === "--package-manager") {
+      if (packageManager !== undefined || !args[index + 1] || args[index + 1].startsWith("-")) throw new Error("Specify one package manager after --package-manager: npm or bun.");
+      packageManager = args[++index];
+    } else if (argument === "--framework") {
+      if (framework !== undefined || !args[index + 1] || args[index + 1].startsWith("-")) throw new Error("Specify one framework after --framework: react or preact.");
+      framework = args[++index];
+    } else if (argument.startsWith("-")) throw new Error("Unknown option. Run ads --help.");
+    else positional.push(argument);
+  }
+  if (positional.length > 2) throw new Error("Extra argument. Run ads --help.");
+  const [command, directory] = positional;
+  if ((port !== undefined || !showcase) && !["mcp", "showcase"].includes(command)) throw new Error("Website options are supported only by mcp/showcase.");
+  if (!showcase && command !== "mcp") throw new Error("--no-showcase is supported only by mcp.");
+  if (mutations && command !== "mcp") throw new Error("--mutations is supported only by mcp.");
+  if (toolPackage !== undefined && command !== "init") throw new Error("--tool-package is supported only by init.");
+  if (packageManager !== undefined && command !== "init") throw new Error("--package-manager is supported only by init.");
+  if (framework !== undefined && command !== "init") throw new Error("--framework is supported only by init.");
+  if (command === "init" && directory) throw new Error("Run ads init inside the project, without a directory argument.");
+  const target = path.resolve(directory ?? process.cwd());
+  if (command === "mcp" || command === "showcase") {
+    if (json) throw new Error("--json is not supported by mcp/showcase; mcp reserves stdout for JSON-RPC.");
+    const { startAdsMcp } = await import("./mcp/server.mjs");
+    await startAdsMcp(target, { stdio: command === "mcp", showcase, port, mutations });
+    return;
+  }
+  let result;
+  if (command === "init") result = initProject(target, { toolPackage, packageManager, framework });
+  else if (command === "check") result = checkProject(target);
+  else if (command === "tokens") result = inspectTokens(target);
+  else if (command === "assets") result = await generateBrandAssets(target);
+  else if (command === "lint-config") result = generateLintConfig(target);
+  else throw new Error(`Unknown command: ${command}. Run ads --help.`);
+  if (json) console.log(JSON.stringify(result, null, 2));
+  else if (command === "init") console.log(`Initialized ${target}\nFramework: ${result.framework}\nAdded ${result.toolDependency.name} (${result.toolDependency.spec}) as a development dependency.\nRun ${result.packageManager} install and ${result.packageManager} run build; the build refreshes lint configuration, runs ADS checks, and generates configured brand assets automatically.`);
+  else if (command === "assets") console.log(result.skipped ? "No assets.iconSource configured; brand generation skipped." : `Generated ${result.files.length} brand assets in ${result.directory}.`);
+  else if (command === "lint-config") console.log(`Generated ${result.file}\nProjects initialized with ads init refresh this automatically during lint:ds/build.`);
+  else if (command === "tokens") {
+    for (const token of result.tokens) console.log(`${token.name}${token.type ? ` (${token.type})` : ""}: ${token.definitions.map((entry) => `${entry.scope}: ${entry.value}`).join("; ")}`);
+  } else if (result.ok) console.log(`ADS check passed: ${target}`);
+  if (!json && result.diagnostics?.length) {
+    for (const diagnostic of result.diagnostics) console.error(`${diagnostic.file}:${diagnostic.line}:${diagnostic.column} [${diagnostic.rule}] ${diagnostic.message}`);
+  }
+  if (result.ok === false || result.diagnostics?.length) process.exitCode = 1;
+}
+
+main(process.argv.slice(2)).catch((error) => {
+  if (process.argv.includes("--json")) console.log(JSON.stringify({ ok: false, error: error.message }));
+  else console.error(`ads: ${error.message}`);
+  process.exitCode = 2;
+});

package/dist/config.mjs

@@ -0,0 +1,181 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { isSharedToken } from "./token-policy.mjs";
+
+export const supportedFrameworks = ["react", "preact"];
+
+export const defaultConfig = {
+  schemaVersion: 1,
+  framework: null,
+  sourceDir: "src",
+  dsDir: "design-system",
+  publicAlias: "@ds",
+  publicEntry: "index.ts",
+  stylesEntry: "styles.css",
+  tokenDir: "tokens",
+  inlineStyleFiles: [],
+  boundaries: { styleWrites: [], componentVariables: [] },
+  assets: { publicDirs: ["public/assets"], generatedPaths: ["dist", "dist-showcase", ".vite", ".ds"], generatedFiles: [], iconSource: null },
+  oxlint: { plugins: [], rules: {}, overrides: [] },
+  mcp: { showcaseUrl: null, showcaseTitle: null, apps: [], previewWatch: null, previewManifest: null, mutationChecks: null },
+};
+
+export function isInside(parent, file) {
+  const relative = path.relative(parent, file);
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+export function projectPath(root, value, field) {
+  if (typeof value !== "string" || !value.trim() || path.isAbsolute(value)) {
+    throw new Error(`${field} must be a non-empty relative path.`);
+  }
+  const absolute = path.resolve(root, value);
+  if (!isInside(root, absolute)) throw new Error(`${field} must stay inside ${root}.`);
+  return absolute;
+}
+
+export function loadConfig(directory = process.cwd()) {
+  const root = path.resolve(directory);
+  const configFile = path.join(root, "ds.config.json");
+  const user = existsSync(configFile) ? JSON.parse(readFileSync(configFile, "utf8")) : {};
+  if (!user || typeof user !== "object" || Array.isArray(user)) throw new Error("ds.config.json must be an object.");
+  for (const field of Object.keys(user)) {
+    if (!(field in defaultConfig)) throw new Error(`Unknown ADS configuration field: ${field}`);
+  }
+  if (user.oxlint !== undefined && (!user.oxlint || typeof user.oxlint !== "object" || Array.isArray(user.oxlint))) throw new Error("oxlint must be an object.");
+  for (const field of ["boundaries", "assets", "oxlint", "mcp"]) {
+    if (user[field] !== undefined && (!user[field] || typeof user[field] !== "object" || Array.isArray(user[field]))) throw new Error(`${field} must be an object.`);
+    for (const key of Object.keys(user[field] ?? {})) if (!(key in defaultConfig[field])) throw new Error(`Unknown ${field} configuration field: ${key}`);
+  }
+  const config = { ...defaultConfig, ...user, boundaries: { ...defaultConfig.boundaries, ...user.boundaries }, assets: { ...defaultConfig.assets, ...user.assets }, oxlint: { ...defaultConfig.oxlint, ...user.oxlint }, mcp: { ...defaultConfig.mcp, ...user.mcp } };
+  if (config.schemaVersion !== 1) throw new Error(`Unsupported ADS config version: ${config.schemaVersion}`);
+  if (user.framework !== undefined && !supportedFrameworks.includes(user.framework)) throw new Error("framework must be react or preact.");
+  if (typeof config.publicAlias !== "string" || !config.publicAlias.trim()) throw new Error("publicAlias must be a non-empty string.");
+  if (!Array.isArray(config.inlineStyleFiles)) throw new Error("inlineStyleFiles must be an array of relative paths.");
+  const sourceRoot = projectPath(root, config.sourceDir, "sourceDir");
+  const dsRoot = projectPath(root, config.dsDir, "dsDir");
+  for (const field of ["publicEntry", "stylesEntry", "tokenDir"]) projectPath(dsRoot, config[field], field);
+  for (const file of config.inlineStyleFiles) projectPath(root, file, "inlineStyleFiles");
+  if (!Array.isArray(config.boundaries.componentVariables) || config.boundaries.componentVariables.some((name) => typeof name !== "string" || !/^--ds-[\w-]+$/.test(name) || isStateVariable(name))) throw new Error("boundaries.componentVariables must name non-state --ds-* customization variables.");
+  if (!Array.isArray(config.boundaries.styleWrites)) throw new Error("boundaries.styleWrites must be an array.");
+  const boundaryFiles = new Set();
+  for (const boundary of config.boundaries.styleWrites) {
+    if (!boundary || typeof boundary !== "object" || Array.isArray(boundary) || Object.keys(boundary).some((key) => !["file", "properties"].includes(key))) throw new Error("Each styleWrites boundary requires file and properties.");
+    const file = projectPath(root, boundary.file, "boundaries.styleWrites.file");
+    if (boundaryFiles.has(file)) throw new Error("Duplicate styleWrites file boundary.");
+    boundaryFiles.add(file);
+    if (!Array.isArray(boundary.properties) || !boundary.properties.length || boundary.properties.some((name) => typeof name !== "string" || !/^(?:--[\w-]+|[a-z][a-z0-9-]*)$/.test(name) || name === "css-text" || isStateVariable(name) || isSharedToken(name) || name.startsWith("--") && !/^(?:--ds-|--ux-|--showcase-)/.test(name))) throw new Error("styleWrites.properties must name explicit CSS properties; bulk cssText, shared tokens, foreign prefixes, and primitive-state writes cannot be allowed.");
+  }
+  for (const field of ["publicDirs", "generatedPaths", "generatedFiles"]) {
+    if (!Array.isArray(config.assets[field])) throw new Error(`assets.${field} must be an array.`);
+    for (const entry of config.assets[field]) {
+      const base = field === "generatedFiles" ? path.join(dsRoot, "assets") : root;
+      const absolute = projectPath(base, entry, `assets.${field}`);
+      if (absolute === base) throw new Error(`assets.${field} must name a path below its root.`);
+    }
+  }
+  if (!Array.isArray(config.oxlint.plugins) || !config.oxlint.rules || typeof config.oxlint.rules !== "object" || Array.isArray(config.oxlint.rules)) {
+    throw new Error("oxlint requires plugins (array) and rules (object).");
+  }
+  if (!Array.isArray(config.oxlint.overrides)) throw new Error("oxlint.overrides must be an array.");
+  for (const override of config.oxlint.overrides) {
+    if (!override || typeof override !== "object" || Array.isArray(override) || Object.keys(override).some((key) => !["files", "rules"].includes(key))) throw new Error("Each oxlint override requires files and rules only.");
+    if (!Array.isArray(override.files) || !override.files.length || override.files.some((file) => typeof file !== "string" || !file.trim() || file.startsWith("!") || path.isAbsolute(file) || file.split(/[\\/]/).includes(".."))) throw new Error("oxlint.overrides.files must contain project-relative paths or globs.");
+    if (!override.rules || typeof override.rules !== "object" || Array.isArray(override.rules)) throw new Error("oxlint.overrides.rules must be an object.");
+  }
+  if (config.assets.iconSource !== null) {
+    const source = projectPath(dsRoot, config.assets.iconSource, "assets.iconSource");
+    if (!isInside(path.join(dsRoot, "assets/brand"), source) || path.extname(source).toLowerCase() !== ".svg") throw new Error("assets.iconSource must name an SVG inside the ADS's assets/brand/ folder.");
+  }
+  for (const plugin of config.oxlint.plugins) {
+    if (!plugin || Object.keys(plugin).some((key) => !["name", "path"].includes(key)) || typeof plugin.name !== "string" || !plugin.name || typeof plugin.path !== "string") {
+      throw new Error("Each project Oxlint plugin needs a name and a relative path.");
+    }
+    projectPath(root, plugin.path, "oxlint.plugins.path");
+  }
+  if (config.mcp.showcaseUrl !== null) {
+    let url;
+    try { url = new URL(config.mcp.showcaseUrl); } catch { throw new Error("mcp.showcaseUrl must be an http(s) URL or null."); }
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) throw new Error("mcp.showcaseUrl must be an http(s) URL without credentials.");
+  }
+  if (config.mcp.showcaseTitle !== null && (typeof config.mcp.showcaseTitle !== "string" || !config.mcp.showcaseTitle.trim() || config.mcp.showcaseTitle.length > 120)) throw new Error("mcp.showcaseTitle must be a non-empty title of at most 120 characters or null.");
+  if (!Array.isArray(config.mcp.apps)) throw new Error("mcp.apps must be an array of built project previews.");
+  if (config.mcp.mutationChecks !== null && (!Array.isArray(config.mcp.mutationChecks) || config.mcp.mutationChecks.length > 12 || new Set(config.mcp.mutationChecks).size !== config.mcp.mutationChecks.length || config.mcp.mutationChecks.some(name => typeof name !== "string" || !/^[a-zA-Z0-9][\w:.-]*$/.test(name)))) throw new Error("mcp.mutationChecks must be null or up to 12 unique package script names.");
+  if (config.mcp.previewManifest !== null) {
+    const manifest = projectPath(root, config.mcp.previewManifest, "mcp.previewManifest");
+    if (!isInside(path.join(root, ".ds"), manifest) || path.extname(manifest) !== ".json") throw new Error("mcp.previewManifest must name a generated JSON manifest inside .ds/.");
+  }
+  if (config.mcp.previewWatch !== null) {
+    const watch = config.mcp.previewWatch;
+    if (!watch || typeof watch !== "object" || Array.isArray(watch) || Object.keys(watch).some((key) => !["command", "args"].includes(key)) || typeof watch.command !== "string" || !watch.command.trim() || watch.command.includes("\0") || !Array.isArray(watch.args) || watch.args.some((arg) => typeof arg !== "string" || arg.includes("\0"))) throw new Error("mcp.previewWatch requires command (executable) and args (string array), or null.");
+  }
+  const appIds = new Set();
+  for (const app of config.mcp.apps) {
+    if (!app || typeof app !== "object" || Object.keys(app).some((key) => !["id", "title", "kind", "file", "description"].includes(key)) || !/^[a-z][a-z0-9-]{0,63}$/.test(app.id) || app.id === "tokens" || appIds.has(app.id) || typeof app.title !== "string" || !app.title.trim() || !["components", "patterns", "showcase"].includes(app.kind) || app.description !== undefined && typeof app.description !== "string") throw new Error("Each mcp.apps entry needs a unique id (tokens is reserved), title, kind (components/patterns/showcase), and project-relative HTML file.");
+    const file = projectPath(root, app.file, "mcp.apps.file");
+    if (path.extname(file) !== ".html") throw new Error("mcp.apps.file must be a built, self-contained HTML file.");
+    appIds.add(app.id);
+  }
+  return { root, config, sourceRoot, dsRoot };
+}
+
+export function isStateVariable(name) {
+  return /^--ds-[\w-]+-(?:sel|selected|hover|active|focus|off|disabled)(?:-|$)/.test(name);
+}
+
+export function isTestFile(file) {
+  return /(?:\.(?:test|spec)\.[cm]?[jt]sx?$|[\\/](?:test|tests|__tests__)[\\/])/.test(file);
+}
+
+export function isScenarioFile(file) {
+  return /(?:^|[\\/])Scenario\.[cm]?[jt]sx?$/.test(file) || /\.scenario\.[cm]?[jt]sx?$/.test(file);
+}
+
+export function isFixtureFile(file) {
+  return /(?:^|[\\/])fixtures?\.(?:[cm]?[jt]sx?|json)$/.test(file) || /\.fixtures?\.(?:[cm]?[jt]sx?|json)$/.test(file);
+}
+
+/** File role, rather than folder location, keeps colocated preview code private. */
+export function isDevelopmentFile(file, { dsRoot }) {
+  if (!isInside(dsRoot, file)) return isTestFile(file);
+  const relative = path.relative(dsRoot, file).replaceAll("\\", "/");
+  return isTestFile(file) || isScenarioFile(file) || isFixtureFile(file)
+    || /^(?:showcase|composition)\//.test(relative)
+    || /(?:^|\/)(?:scenario|fixtures)(?:\/|$)/.test(relative)
+    || /\.scenario(?:-adapter)?\.[cm]?[jt]sx?$/.test(relative);
+}
+
+const ignored = new Set(["node_modules", "dist", "dist-showcase", "dist-kit", ".git", ".vite", ".ds", "coverage"]);
+
+export function sourceFiles(root) {
+  if (!existsSync(root)) return [];
+  const files = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (ignored.has(entry.name) || entry.isSymbolicLink()) continue;
+    const file = path.join(root, entry.name);
+    if (entry.isDirectory()) files.push(...sourceFiles(file));
+    else if (entry.isFile() && /\.(css|html|[cm]?[jt]sx?)$/.test(entry.name)) files.push(file);
+  }
+  return files.sort();
+}
+
+export function importViolation(specifier, filename, options, resolve) {
+  const { root, dsRoot, config } = options;
+  // ADS implementation code needs its private imports; the showcase is a consumer.
+  if (isInside(dsRoot, filename) && !isDevelopmentFile(filename, options)) return false;
+  if (specifier.startsWith(`${config.publicAlias}/`)) return true;
+  if (specifier === config.publicAlias) return false;
+  const imported = resolve ? resolve(specifier, filename)
+    : specifier.startsWith(".") ? [path.resolve(path.dirname(filename), specifier)]
+    : specifier.startsWith(`${config.dsDir}/`) ? [path.resolve(root, specifier)] : [];
+  return imported.some((file) => {
+    if (!isInside(dsRoot, file)) return false;
+    // Owner-local white-box tests may exercise private helpers without making
+    // those helpers public API. Scenarios remain public-API consumers.
+    if (isTestFile(filename) && isInside(dsRoot, filename) && isInside(path.dirname(filename), file)) return false;
+    if (isDevelopmentFile(filename, options) && isDevelopmentFile(file, options)) return false;
+    if (isTestFile(filename) && (isInside(path.join(dsRoot, "showcase"), file) || isTestFile(file))) return false;
+    if (isInside(path.join(dsRoot, "showcase"), filename) && isInside(path.join(dsRoot, "showcase"), file)) return false;
+    return file !== path.join(dsRoot, config.stylesEntry);
+  });
+}

package/dist/contracts/tokens.json

@@ -0,0 +1,52 @@
+{
+  "version": 1,
+  "description": "Shared CSS token names, semantics, and value categories. Values belong to the project.",
+  "naming": {
+    "prefixes": ["--color-", "--slate-", "--warm-", "--rose-", "--bg-", "--text-", "--border-", "--font-", "--weight-", "--leading-", "--tracking-", "--type-", "--space-", "--radius-", "--control-", "--icon-", "--shadow-", "--ring-", "--filter-", "--ease-", "--dur-", "--z-", "--accent-", "--focus-", "--scroll-", "--success-", "--warning-", "--danger-", "--info-", "--side-pane-", "--toast-"],
+    "names": ["--accent", "--success", "--warning", "--danger", "--info", "--inset-hairline", "--navigation-rail-width", "--app-header-height", "--content-max", "--row-height-compact", "--compact-column-min", "--stack-gap-compact"]
+  },
+  "tokens": {
+    "--bg-canvas": { "type": "color", "meaning": "Application canvas" },
+    "--bg-surface": { "type": "color", "meaning": "Component surface" },
+    "--bg-hover": { "type": "color", "meaning": "Hovered surface" },
+    "--text-strong": { "type": "color", "meaning": "Strong text" },
+    "--text-body": { "type": "color", "meaning": "Body text" },
+    "--text-muted": { "type": "color", "meaning": "Secondary text" },
+    "--text-inverse": { "type": "color", "meaning": "Text on contrasting fills" },
+    "--border-default": { "type": "color", "meaning": "Default border" },
+    "--border-focus": { "type": "color", "meaning": "Focus border" },
+    "--accent": { "type": "color", "meaning": "Brand accent" },
+    "--accent-hover": { "type": "color", "meaning": "Hovered brand accent" },
+    "--accent-fg": { "type": "color", "meaning": "Foreground on accent" },
+    "--font-sans": { "type": "fontFamily", "meaning": "UI font stack" },
+    "--font-mono": { "type": "fontFamily", "meaning": "Code font stack" },
+    "--text-sm": { "type": "dimension", "meaning": "Small UI text" },
+    "--text-base": { "type": "dimension", "meaning": "Body text size" },
+    "--text-lg": { "type": "dimension", "meaning": "Heading text size" },
+    "--text-xl": { "type": "dimension", "meaning": "Large heading text size" },
+    "--weight-normal": { "type": "number", "meaning": "Normal font weight" },
+    "--weight-medium": { "type": "number", "meaning": "Medium font weight" },
+    "--weight-semibold": { "type": "number", "meaning": "Semibold font weight" },
+    "--leading-tight": { "type": "number", "meaning": "Tight line height" },
+    "--leading-normal": { "type": "number", "meaning": "Normal line height" },
+    "--space-0": { "type": "dimension", "meaning": "Zero spacing" },
+    "--space-2": { "type": "dimension", "meaning": "Spacing step 2" },
+    "--space-4": { "type": "dimension", "meaning": "Spacing step 4" },
+    "--space-6": { "type": "dimension", "meaning": "Spacing step 6" },
+    "--space-8": { "type": "dimension", "meaning": "Spacing step 8" },
+    "--space-12": { "type": "dimension", "meaning": "Spacing step 12" },
+    "--space-16": { "type": "dimension", "meaning": "Spacing step 16" },
+    "--radius-sm": { "type": "dimension", "meaning": "Small radius" },
+    "--radius-md": { "type": "dimension", "meaning": "Medium radius" },
+    "--radius-lg": { "type": "dimension", "meaning": "Large radius" },
+    "--border-w": { "type": "dimension", "meaning": "Default border width" },
+    "--focus-w": { "type": "dimension", "meaning": "Focus ring width" },
+    "--focus-offset": { "type": "dimension", "meaning": "Focus ring offset" },
+    "--shadow-xs": { "type": "shadow", "meaning": "Subtle shadow" },
+    "--shadow-raised": { "type": "shadow", "meaning": "Raised surface shadow" },
+    "--dur-fast": { "type": "duration", "meaning": "Fast transition duration" },
+    "--dur-normal": { "type": "duration", "meaning": "Standard transition duration" },
+    "--ease-standard": { "type": "easing", "meaning": "Standard transition curve" },
+    "--z-overlay": { "type": "number", "meaning": "Overlay stacking level" }
+  }
+}

package/dist/html.mjs

@@ -0,0 +1,30 @@
+import postcss from "postcss";
+
+// The only non-ADS CSS boundary is document mounting. This is a fixed grammar,
+// not permission for application selectors or additional visual declarations.
+export function isMountCss(text) {
+  try {
+    const css = postcss.parse(text);
+    let declarations = 0;
+    for (const rule of css.nodes.filter((node) => node.type !== "comment")) {
+      if (rule.type !== "rule") return false;
+      const selectors = rule.selector.split(",").map((selector) => selector.trim());
+      if (!selectors.length || selectors.some((selector) => !["html", "body", "#root"].includes(selector))) return false;
+      for (const decl of rule.nodes.filter((node) => node.type !== "comment")) {
+        if (decl.type !== "decl" || decl.important) return false;
+        if (!(decl.prop === "height" && decl.value === "100%" || decl.prop === "overflow" && decl.value === "hidden" && selectors.every((selector) => selector === "body"))) return false;
+        declarations++;
+      }
+    }
+    return declarations > 0;
+  } catch { return false; }
+}
+
+export function inspectHtml(text, report) {
+  const clean = text.replace(/<!--[\s\S]*?-->/g, (comment) => comment.replace(/[^\n]/g, " "));
+  for (const match of clean.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi)) {
+    if (!isMountCss(match[1])) report("html-style", "HTML styles may only set html/body/#root height: 100% and body overflow: hidden. Put visual CSS in ADS owners.", clean.slice(0, match.index).split("\n").length);
+  }
+  const markup = clean.replace(/<(?:script|style)\b[^>]*>[\s\S]*?<\/(?:script|style)\s*>/gi, (block) => block.replace(/[^\n]/g, " "));
+  for (const match of markup.matchAll(/<[a-z][\w:-]*\b[^>]*\sstyle\s*=/gi)) report("html-style", "HTML style attributes are not a visual customization boundary. Use the ADS foundation and components.", markup.slice(0, match.index).split("\n").length);
+}

package/dist/index.mjs

@@ -0,0 +1,9 @@
+export { initProject } from "./init.mjs";
+export { checkProject } from "./check.mjs";
+export { inspectTokens, tokenContract } from "./tokens.mjs";
+export { generateLintConfig } from "./lint-config.mjs";
+export { generateBrandAssets } from "./brand-assets.mjs";
+// Node-only helpers for registered project lint extensions. They reuse the
+// same validated configuration and property boundary as the core checker.
+export { loadConfig } from "./config.mjs";
+export { importResolver, styleWriteViolation } from "./boundaries.mjs";

package/dist/init.mjs

@@ -0,0 +1,194 @@
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, writeFileSync, chmodSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isInside, loadConfig, sourceFiles, supportedFrameworks } from "./config.mjs";
+import { createLintConfig } from "./lint-config.mjs";
+import { foundationFiles } from "./token-policy.mjs";
+import { assertFrameworkCompiler } from "./ui-framework.mjs";
+
+const tool = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const starter = fileURLToPath(new URL("./bootstrap-ds/", import.meta.url));
+const starterPackage = JSON.parse(readFileSync(path.join(starter, "package.json"), "utf8"));
+
+function dependencySpec(value) {
+  if (typeof value !== "string" || !value.trim()) throw new Error("toolPackage must be a version or local tool tarball path.");
+  if (value.startsWith(`${tool.name}@`)) return dependencySpec(value.slice(tool.name.length + 1));
+  if (value.startsWith("file:")) {
+    const local = value.startsWith("file://") ? fileURLToPath(value) : value.slice(5);
+    if (!local) throw new Error("Specify a local tool tarball after file:.");
+    return `file:${path.resolve(local)}`;
+  }
+  if (path.isAbsolute(value) || value.startsWith(".") || value.endsWith(".tgz")) return `file:${path.resolve(value)}`;
+  return value;
+}
+
+function detectManager(root, pkg, requested) {
+  if (requested !== undefined) return requested;
+  if (typeof pkg.packageManager === "string") return pkg.packageManager.split("@")[0];
+  const bun = ["bun.lock", "bun.lockb"].some((name) => existsSync(path.join(root, name)));
+  const npm = existsSync(path.join(root, "package-lock.json"));
+  if (bun && npm) throw new Error("Both Bun and npm lockfiles exist. Specify --package-manager bun or npm.");
+  if (bun) return "bun";
+  if (npm) return "npm";
+  if (["pnpm-lock.yaml", "yarn.lock"].some((name) => existsSync(path.join(root, name)))) throw new Error("This version supports npm and Bun projects.");
+  return process.env.npm_config_user_agent?.startsWith("bun/") ? "bun" : "npm";
+}
+
+function assertLocalFile(root, file) {
+  if (!isInside(root, file)) throw new Error(`Init writes must stay inside ${root}.`);
+  for (let current = file; isInside(root, current); current = path.dirname(current)) {
+    const stat = lstatSync(current, { throwIfNoEntry: false });
+    if (stat?.isSymbolicLink()) throw new Error(`Init does not write through symlinks: ${current}`);
+    if (current === file && stat && !stat.isFile()) throw new Error(`Expected a file: ${file}`);
+    if (current !== file && stat && !stat.isDirectory()) throw new Error(`Expected a directory: ${current}`);
+    if (current === root) break;
+  }
+}
+
+function commit(root, updates) {
+  const entries = [...updates].map(([file, content]) => {
+    assertLocalFile(root, file);
+    const stat = lstatSync(file, { throwIfNoEntry: false });
+    return { file, content, before: stat ? readFileSync(file) : null, mode: stat?.mode };
+  });
+  const staging = mkdtempSync(path.join(root, ".ads-init-"));
+  const directories = [];
+  const written = [];
+  function makeDirectory(directory) {
+    if (existsSync(directory)) return;
+    makeDirectory(path.dirname(directory));
+    mkdirSync(directory);
+    directories.push(directory);
+  }
+  try {
+    for (const [index, entry] of entries.entries()) {
+      const current = existsSync(entry.file) ? readFileSync(entry.file) : null;
+      if ((current === null) !== (entry.before === null) || (current && !current.equals(entry.before))) throw new Error(`Project file changed during init: ${entry.file}`);
+      const temporary = path.join(staging, String(index));
+      writeFileSync(temporary, entry.content);
+      if (entry.mode !== undefined) chmodSync(temporary, entry.mode);
+      makeDirectory(path.dirname(entry.file));
+      renameSync(temporary, entry.file);
+      written.push(entry);
+    }
+  } catch (error) {
+    for (const [index, entry] of written.toReversed().entries()) {
+      if (entry.before === null) rmSync(entry.file);
+      else {
+        const restored = path.join(staging, `restore-${index}`);
+        writeFileSync(restored, entry.before);
+        chmodSync(restored, entry.mode);
+        renameSync(restored, entry.file);
+      }
+    }
+    for (const directory of directories.toReversed()) if (!readdirSync(directory).length) rmdirSync(directory);
+    throw error;
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+export function initProject(directory = process.cwd(), { toolPackage, packageManager, framework } = {}) {
+  const root = path.resolve(directory);
+  const packageFile = path.join(root, "package.json");
+  assertLocalFile(root, packageFile);
+  if (!existsSync(packageFile)) throw new Error("Run ads init inside an existing project containing package.json.");
+  const originalPackage = readFileSync(packageFile, "utf8");
+  const pkg = JSON.parse(originalPackage);
+  if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) throw new Error("package.json must be an object.");
+  for (const field of ["scripts", "dependencies", "devDependencies"]) {
+    if (pkg[field] !== undefined && (!pkg[field] || typeof pkg[field] !== "object" || Array.isArray(pkg[field]))) throw new Error(`package.json ${field} must be an object.`);
+  }
+  for (const [name, script] of Object.entries(pkg.scripts ?? {})) {
+    if (typeof script !== "string") throw new Error(`package.json script ${name} must be a string.`);
+  }
+  const manager = detectManager(root, pkg, packageManager);
+  if (!["npm", "bun"].includes(manager)) throw new Error("packageManager must be npm or bun.");
+  const run = `${manager} run`;
+  const spec = dependencySpec(toolPackage ?? pkg.devDependencies?.[tool.name] ?? pkg.dependencies?.[tool.name] ?? tool.version);
+  const { config, dsRoot } = loadConfig(root);
+  if (framework !== undefined && !supportedFrameworks.includes(framework)) throw new Error("framework must be react or preact.");
+  if (framework !== undefined && config.framework !== null && framework !== config.framework) throw new Error(`ADS is configured for ${config.framework}; --framework ${framework} would change it. Migrate the project and update ds.config.json explicitly before running init.`);
+  const selectedFramework = framework ?? config.framework;
+  if (selectedFramework === null) throw new Error("Specify --framework react or --framework preact on first init, including when adopting an existing ADS config without a framework.");
+  assertFrameworkCompiler(root, selectedFramework);
+  config.framework = selectedFramework;
+  const lintRoots = [config.sourceDir];
+  if (!isInside(path.resolve(root, config.sourceDir), dsRoot)) lintRoots.push(config.dsDir);
+  const sourceArguments = lintRoots.map((directory) => `'${directory.replaceAll("'", "'\"'\"'")}'`).join(" ");
+  const lint = `ads lint-config . && ads check . && oxlint --deny-warnings --config .ds/oxlintrc.json ${sourceArguments}`;
+  const scripts = { ...pkg.scripts };
+  if (scripts["lint:ds"] && scripts["lint:ds"] !== lint && !["ads lint-config . && ads check .", "ds lint-config . && ds check ."].some(prefix => scripts["lint:ds"].startsWith(prefix))) throw new Error("An existing custom lint:ds script would conflict. Rename it or integrate ADS checks before running init.");
+  scripts["lint:ds"] = lint;
+  if (scripts["assets:ds"] && !["ads assets", "ds assets"].includes(scripts["assets:ds"])) throw new Error("An existing custom assets:ds script would conflict. Rename it or integrate ADS asset generation before running init.");
+  scripts["assets:ds"] = "ads assets";
+  if (!scripts["dev:showcase"] || scripts["dev:showcase"] === "ds showcase") scripts["dev:showcase"] = "ads showcase";
+  scripts["ads-mcp"] ??= "ads mcp --mutations";
+  scripts["ads-read-mcp"] ??= "ads mcp";
+  const managedBuild = [`${run} lint:ds`, `${run} lint:ds && ${run} assets:ds`].includes(scripts.build);
+  if (scripts.build && !managedBuild) {
+    const previous = scripts.prebuild ?? "";
+    const remaining = previous.replace(/^(?:npm|bun) run lint:ds(?:\s*&&\s*(?:npm|bun) run assets:ds)?(?:\s*&&\s*|$)/, "");
+    scripts.prebuild = `${run} lint:ds && ${run} assets:ds${remaining ? ` && ${remaining}` : ""}`;
+  } else scripts.build = `${run} lint:ds && ${run} assets:ds`;
+  if (scripts["build:showcase"]) {
+    const previous = scripts["prebuild:showcase"] ?? "";
+    const remaining = previous.replace(/^(?:npm|bun) run lint:ds(?:\s*&&\s*(?:npm|bun) run assets:ds)?(?:\s*&&\s*|$)/, "");
+    scripts["prebuild:showcase"] = `${run} lint:ds && ${run} assets:ds${remaining ? ` && ${remaining}` : ""}`;
+  }
+  pkg.scripts = scripts;
+  pkg.devDependencies = { ...pkg.devDependencies, [tool.name]: spec };
+  if (!pkg.devDependencies.oxlint && !pkg.dependencies?.oxlint) pkg.devDependencies.oxlint = starterPackage.devDependencies.oxlint;
+  if (pkg.dependencies?.[tool.name]) delete pkg.dependencies[tool.name];
+
+  const updates = new Map();
+  function addMissing(file, content) { assertLocalFile(root, file); if (!existsSync(file)) updates.set(file, content); }
+  const tokenRoot = path.join(dsRoot, config.tokenDir);
+  const existingTokens = sourceFiles(tokenRoot).filter((file) => file.endsWith(".css"));
+  const tokenFiles = existingTokens.length ? existingTokens : foundationFiles.filter((name) => existsSync(path.join(starter, "design-system/tokens", name))).map((name) => {
+    const file = path.join(tokenRoot, name);
+    addMissing(file, readFileSync(path.join(starter, "design-system/tokens", name)));
+    return file;
+  });
+  if (!existingTokens.length) {
+    for (const name of ["Foundation.scenario.tsx", "Foundation.fixture.ts"]) {
+      let content = readFileSync(path.join(starter, "design-system/tokens", name), "utf8");
+      if (selectedFramework === "preact" && name === "Foundation.scenario.tsx") content = content.replace('from "react"', 'from "preact/hooks"');
+      addMissing(path.join(tokenRoot, name), content);
+    }
+  }
+  tokenFiles.sort((a, b) => foundationFiles.indexOf(path.basename(a)) - foundationFiles.indexOf(path.basename(b)) || a.localeCompare(b));
+  const stylesFile = path.join(dsRoot, config.stylesEntry);
+  const relativeImport = (from, to) => {
+    const relative = path.relative(path.dirname(from), to).split(path.sep).join("/");
+    return relative.startsWith(".") ? relative : `./${relative}`;
+  };
+  addMissing(stylesFile, tokenFiles.map((file) => `@import ${JSON.stringify(relativeImport(stylesFile, file))};`).join("\n") + "\n");
+  const entryFile = path.join(dsRoot, config.publicEntry);
+  addMissing(entryFile, `// Export your project's public components and types here.\nimport ${JSON.stringify(relativeImport(entryFile, stylesFile))};\nexport {};\n`);
+  for (const section of ["components", "patterns", "composition"]) addMissing(path.join(dsRoot, section, ".gitkeep"), "");
+  addMissing(path.join(dsRoot, "assets/brand/README.md"), readFileSync(path.join(starter, "design-system/assets/brand/README.md")));
+  addMissing(path.join(dsRoot, "assets/fonts/.gitkeep"), "");
+  const configFile = path.join(root, "ds.config.json");
+  assertLocalFile(root, configFile);
+  if (!existsSync(configFile)) updates.set(configFile, `${JSON.stringify(config, null, 2)}\n`);
+  else {
+    const original = readFileSync(configFile, "utf8");
+    const saved = JSON.parse(original);
+    if (saved.framework === undefined) {
+      const indent = original.match(/\n([\t ]+)"/)?.[1] ?? "  ";
+      updates.set(configFile, `${JSON.stringify({ ...saved, framework: selectedFramework }, null, indent)}\n`);
+    }
+  }
+  const lintConfigFile = path.join(root, ".ds/oxlintrc.json");
+  updates.set(lintConfigFile, `${JSON.stringify(createLintConfig({ root, config }), null, 2)}\n`);
+  const ignoreFile = path.join(root, ".gitignore");
+  assertLocalFile(root, ignoreFile);
+  const ignore = existsSync(ignoreFile) ? readFileSync(ignoreFile, "utf8") : "";
+  if (!ignore.split(/\r?\n/).some((line) => [".ds/", ".ds", "/.ds/", "/.ds"].includes(line))) updates.set(ignoreFile, `${ignore}${ignore && !ignore.endsWith("\n") ? "\n" : ""}.ds/\n`);
+  const indent = originalPackage.match(/\n([\t ]+)"/)?.[1] ?? "  ";
+  const nextPackage = `${JSON.stringify(pkg, null, indent)}\n`;
+  if (nextPackage !== originalPackage) updates.set(packageFile, nextPackage);
+  commit(root, updates);
+  return { directory: root, framework: selectedFramework, packageManager: manager, lintConfig: lintConfigFile, toolDependency: { name: tool.name, spec }, updatedFiles: [...updates.keys()] };
+}

package/dist/lint-config.mjs

@@ -0,0 +1,40 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadConfig } from "./config.mjs";
+import { configurationFiles } from "./units.mjs";
+
+export function createLintConfig({ root, config }) {
+  const names = new Set(["ads"]);
+  const projectPlugins = config.oxlint.plugins.map((plugin) => {
+    if (names.has(plugin.name)) throw new Error(`Duplicate or reserved Oxlint plugin name: ${plugin.name}`);
+    names.add(plugin.name);
+    const specifier = path.resolve(root, plugin.path);
+    if (!existsSync(specifier)) throw new Error(`Project plugin not found: ${plugin.path}`);
+    return { name: plugin.name, specifier };
+  });
+  const options = { projectRoot: root, sourceDir: config.sourceDir, dsDir: config.dsDir, publicAlias: config.publicAlias, stylesEntry: config.stylesEntry, inlineStyleFiles: config.inlineStyleFiles,
+    configurationFiles: [...configurationFiles({ root, config, sourceRoot: path.resolve(root,config.sourceDir), dsRoot: path.resolve(root,config.dsDir) })].sort() };
+  return {
+    jsPlugins: [{ name: "ads", specifier: fileURLToPath(new URL("./oxlint.mjs", import.meta.url)) }, ...projectPlugins],
+    rules: {
+      "ads/public-import": ["error", options],
+      "ads/no-inline-style": ["error", options],
+      "ads/no-app-import": ["error", options],
+      "ads/showcase-import": ["error", options],
+      ...config.oxlint.rules,
+    },
+    // The generated config lives in .ds/. Resolve project-relative file globs
+    // here so the same scoped policy survives a relocated checkout.
+    overrides: config.oxlint.overrides.map((override) => ({ ...override, files: override.files.map((file) => path.resolve(root, file).replaceAll("\\", "/")) })),
+  };
+}
+
+export function generateLintConfig(directory) {
+  const project = loadConfig(directory);
+  const generated = createLintConfig(project);
+  const file = path.join(project.root, ".ds", "oxlintrc.json");
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(generated, null, 2)}\n`);
+  return { file };
+}