canon-ds 0.1.0

package/lib/connect.mjs

@@ -0,0 +1,110 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+import { buildSystem } from "./build.mjs";
+import { installFiles, loadSource, sourcePath, validateSnapshot } from "./design-files.mjs";
+import { install } from "./install.mjs";
+import { findProject } from "./project.mjs";
+import { writeDesignDir } from "./system.mjs";
+import { compareSpecs } from "./components/index.mjs";
+import { comparePatterns } from "./patterns/index.mjs";
+const MAX_SNAPSHOT_BYTES = 8 * 1024 * 1024;
+async function readSnapshot(source) {
+    if (!/^https?:\/\//i.test(source)) {
+        if (statSync(source).size > MAX_SNAPSHOT_BYTES)
+            throw new Error('Design snapshot exceeds 8 MiB');
+        return JSON.parse(readFileSync(source, 'utf8'));
+    }
+    const base = new URL(source);
+    base.search = '';
+    base.hash = '';
+    // Public catalogs can live at /canon/ on a static host. Keep that directory
+    // for both the document URL and a site address copied from the browser.
+    if (!base.pathname.endsWith('/') && !base.pathname.split('/').at(-1).includes('.'))
+        base.pathname += '/';
+    const url = new URL('./api/system', base);
+    const response = await fetch(url, { signal: AbortSignal.timeout(15_000), redirect: 'error' });
+    if (!response.ok)
+        throw new Error(`Could not read the saved Studio design (HTTP ${response.status})`);
+    if (Number(response.headers.get('content-length') ?? 0) > MAX_SNAPSHOT_BYTES) {
+        await response.body?.cancel();
+        throw new Error('Design snapshot exceeds 8 MiB');
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('Studio returned no design snapshot');
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_SNAPSHOT_BYTES)
+                throw new Error('Design snapshot exceeds 8 MiB');
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel();
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+export async function connect(source, opts) {
+    mkdirSync(opts.root, { recursive: true });
+    const root = realpathSync(resolve(opts.root));
+    const project = findProject(root);
+    const design = opts.design ? resolve(root, opts.design) : project?.root === root ? project.design : join(root, 'design');
+    // New sources must be inside the selected project; explicitly configured existing
+    // sources may live elsewhere, but are still checked against their own boundary.
+    const existing = existsSync(join(design, 'system.json'));
+    const rel = relative(root, design);
+    const inside = !isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`);
+    if (!existing || inside)
+        sourcePath(root, design, 'directory');
+    else if (realpathSync(design) !== design)
+        throw new Error('Canon does not connect through linked design directories');
+    let reused = false;
+    if (existing) {
+        const system = validateSnapshot(loadSource(realpathSync(design)));
+        const stage = mkdtempSync(join(tmpdir(), 'canon-reconnect-'));
+        try {
+            const result = await buildSystem(system, stage);
+            installFiles(design, result.files.map(file => ({
+                path: join(design, system.meta.out, relative(result.outDir, file)), content: readFileSync(file),
+            })));
+        }
+        finally {
+            rmSync(stage, { recursive: true, force: true });
+        }
+        reused = true;
+    }
+    else {
+        if (existsSync(design) && readdirSync(design).length)
+            throw new Error(`Design destination is not empty: ${design}`);
+        if (!source)
+            throw new Error('Provide the Studio URL or a saved design snapshot to connect this project');
+        const system = validateSnapshot(await readSnapshot(source));
+        system.components.sort(compareSpecs);
+        system.patterns.sort(comparePatterns);
+        mkdirSync(dirname(design), { recursive: true });
+        const stage = mkdtempSync(join(dirname(design), '.canon-connect-'));
+        try {
+            writeDesignDir(system, stage);
+            await buildSystem(system, stage);
+            sourcePath(root, design, 'directory');
+            if (existsSync(design)) {
+                if (readdirSync(design).length)
+                    throw new Error(`Design destination is not empty: ${design}`);
+                rmSync(design, { recursive: true });
+            }
+            renameSync(stage, design);
+        }
+        finally {
+            rmSync(stage, { recursive: true, force: true });
+        }
+    }
+    const { log } = install(loadSource(realpathSync(design)), design, { root, hooks: opts.hooks !== false });
+    return { design, reused, log };
+}

package/lib/design-files.mjs

@@ -0,0 +1,175 @@
+// Shared design validation and rollback-capable local file writes.
+import { readFileSync, writeFileSync, mkdirSync, lstatSync, realpathSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { join, resolve, relative, isAbsolute, sep, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { loadDesignDir, validateSystem } from "./system.mjs";
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export class HttpError extends Error {
+    status;
+    constructor(status, message) { super(message); this.status = status; }
+}
+export function requireValue(condition, message) {
+    if (!condition)
+        throw new HttpError(400, message);
+}
+export function record(value, name) {
+    requireValue(value !== null && typeof value === 'object' && !Array.isArray(value), `${name} must be an object`);
+    return value;
+}
+function strings(value, name) {
+    requireValue(Array.isArray(value) && value.every((item) => typeof item === 'string'), `${name} must be an array of strings`);
+}
+export function identifier(value, name) {
+    requireValue(typeof value === 'string' && value.length <= 128 && SLUG.test(value), `${name} must be a lowercase slug`);
+}
+export function validateMeta(value, designRoot, outputRoot) {
+    const meta = record(value, 'meta');
+    for (const key of ['name', 'version'])
+        requireValue(typeof meta[key] === 'string' && meta[key].trim(), `meta.${key} must be a nonempty string`);
+    identifier(meta.prefix, 'meta.prefix');
+    requireValue(meta.description === undefined || typeof meta.description === 'string', 'meta.description must be a string');
+    requireValue(meta.defaultTheme === 'light' || meta.defaultTheme === 'dark', 'meta.defaultTheme must be light or dark');
+    const direction = record(meta.direction, 'meta.direction');
+    requireValue(typeof direction.summary === 'string', 'meta.direction.summary must be a string');
+    strings(direction.principles, 'meta.direction.principles');
+    strings(direction.never, 'meta.direction.never');
+    const seeds = record(meta.seeds, 'meta.seeds');
+    for (const key of ['name', 'prefix', 'brand'])
+        requireValue(typeof seeds[key] === 'string', `meta.seeds.${key} must be a string`);
+    identifier(seeds.prefix, 'meta.seeds.prefix');
+    for (const key of ['action', 'canvasLight', 'inkDark', 'fontSans', 'fontMono', 'fontDisplay', 'shadowTint'])
+        requireValue(seeds[key] === undefined || typeof seeds[key] === 'string', `meta.seeds.${key} must be a string`);
+    for (const key of ['neutralHue', 'neutralChroma', 'radiusScale', 'baseFontSize', 'controlHeight'])
+        requireValue(seeds[key] === undefined || (typeof seeds[key] === 'number' && Number.isFinite(seeds[key])), `meta.seeds.${key} must be a finite number`);
+    requireValue(seeds.defaultTheme === undefined || seeds.defaultTheme === 'light' || seeds.defaultTheme === 'dark', 'meta.seeds.defaultTheme must be light or dark');
+    for (const key of ['overrides', 'presetOverrides'])
+        if (seeds[key] !== undefined)
+            record(seeds[key], `meta.seeds.${key}`);
+    const lint = record(meta.lint, 'meta.lint');
+    for (const key of ['include', 'exclude', 'allow'])
+        strings(lint[key], `meta.lint.${key}`);
+    requireValue(typeof lint.tailwind === 'boolean', 'meta.lint.tailwind must be a boolean');
+    const icons = record(meta.icons, 'meta.icons');
+    for (const key of ['set', 'strokeWidth', 'note'])
+        requireValue(typeof icons[key] === 'string', `meta.icons.${key} must be a string`);
+    requireValue(typeof meta.out === 'string' && meta.out.length > 0 && !isAbsolute(meta.out) && !meta.out.includes('\\') && meta.out.split('/').every((part) => part !== '.' && part !== '..' && /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(part)), 'meta.out must be a relative output directory');
+    requireValue(!['components', 'patterns', 'system.json', 'tokens.json'].includes(meta.out.split('/')[0]), 'meta.out must not overlap design source files');
+    // Keep an active Studio attached to its configured output; changing it requires a restart.
+    requireValue(resolve(designRoot, meta.out) === outputRoot, 'Studio cannot change meta.out; use the configured output directory');
+}
+export function contained(root, path) {
+    const rel = relative(root, path);
+    if (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`))
+        throw new HttpError(403, 'Path is outside the Studio directory');
+}
+export function maybeStat(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+/** Source/output writes reject symlinks, including dangling links and linked parents. */
+export function sourcePath(root, path, kind) {
+    contained(root, path);
+    if (realpathSync(root) !== root)
+        throw new HttpError(403, 'The Studio design directory has moved');
+    const parts = relative(root, path).split(sep).filter(Boolean);
+    let current = root;
+    for (let i = -1; i < parts.length; i++) {
+        if (i >= 0)
+            current = join(current, parts[i]);
+        const info = maybeStat(current);
+        if (!info)
+            continue;
+        if (info.isSymbolicLink())
+            throw new HttpError(403, 'Studio does not read or write design files through symlinks');
+        const directory = i < parts.length - 1 || kind === 'directory';
+        if (directory ? !info.isDirectory() : !info.isFile())
+            throw new HttpError(409, 'A Studio path has the wrong file type');
+    }
+    return path;
+}
+export function loadSource(root) {
+    for (const file of ['system.json', 'tokens.json'])
+        sourcePath(root, join(root, file), 'file');
+    for (const folder of ['components', 'patterns']) {
+        const path = sourcePath(root, join(root, folder), 'directory');
+        if (maybeStat(path))
+            for (const file of readdirSync(path))
+                if (file.endsWith('.json'))
+                    sourcePath(root, join(path, file), 'file');
+    }
+    return loadDesignDir(root);
+}
+/** Validate a complete imported snapshot before creating any source/output files. */
+export function validateSnapshot(value) {
+    const source = record(value, 'Design snapshot');
+    const meta = record(source.meta, 'meta');
+    requireValue(typeof meta.out === 'string', 'meta.out must be a relative output directory');
+    const root = resolve('.');
+    validateMeta(meta, root, resolve(root, meta.out));
+    record(source.tokens, 'tokens');
+    for (const collection of ['components', 'patterns']) {
+        requireValue(Array.isArray(source[collection]), `${collection} must be an array`);
+        const slugs = new Set();
+        for (const item of source[collection]) {
+            const spec = record(item, `${collection} entry`);
+            identifier(spec.slug, `${collection} slug`);
+            requireValue(!slugs.has(spec.slug), `Duplicate ${collection} slug: ${spec.slug}`);
+            slugs.add(spec.slug);
+        }
+    }
+    const system = source;
+    const validation = validateSystem(system);
+    requireValue(!validation.errors.length, validation.errors.slice(0, 5).join('; '));
+    return system;
+}
+function replaceFile(root, write, content) {
+    sourcePath(write.root ?? root, write.path, 'file');
+    mkdirSync(dirname(write.path), { recursive: true });
+    const temporary = join(dirname(write.path), `.canon-${randomUUID()}.tmp`);
+    try {
+        writeFileSync(temporary, content, { flag: 'wx', mode: write.mode ?? 0o644 });
+        sourcePath(write.root ?? root, write.path, 'file');
+        renameSync(temporary, write.path);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+/** Preflight all destinations before mutation, then replace files atomically and roll back errors. */
+export function installFiles(root, writes) {
+    for (const write of writes) {
+        sourcePath(write.root ?? root, write.path, 'file');
+        const info = maybeStat(write.path);
+        if (info) {
+            write.previous = readFileSync(write.path);
+            write.mode = info.mode & 0o777;
+        }
+    }
+    const installed = [];
+    try {
+        for (const write of writes) {
+            replaceFile(write.root ?? root, write, write.content);
+            installed.push(write);
+        }
+    }
+    catch (error) {
+        for (const write of installed.reverse()) {
+            try {
+                if (write.previous !== undefined)
+                    replaceFile(write.root ?? root, write, write.previous);
+                else {
+                    sourcePath(write.root ?? root, write.path, 'file');
+                    rmSync(write.path);
+                }
+            }
+            catch { /* Preserve the original failure; never follow a changed filesystem boundary. */ }
+        }
+        throw error;
+    }
+}

package/lib/distribution.mjs

@@ -0,0 +1,109 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { copyFile, cp, lstat, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+const execute = promisify(execFile);
+// Both src/distribution.ts and installed lib/distribution.mjs live one level below the package root.
+const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+const require = createRequire(import.meta.url);
+let archive;
+async function copyRuntime(source, destination) {
+    await cp(source, destination, {
+        recursive: true,
+        filter: async (path) => {
+            const info = await lstat(path);
+            if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile())) {
+                throw new Error('Canon distribution requires regular package files; linked files cannot be included.');
+            }
+            return !basename(path).startsWith('.');
+        },
+    });
+}
+async function run(command, args, cwd, temporary, label) {
+    try {
+        return await execute(command, args, {
+            cwd, timeout: 60_000, maxBuffer: 2 * 1024 * 1024, windowsHide: true,
+            env: {
+                ...process.env, npm_config_ignore_scripts: 'true',
+                TMPDIR: temporary, TMP: temporary, TEMP: temporary, NODE_COMPILE_CACHE: join(temporary, 'node-compile-cache'),
+            },
+        });
+    }
+    catch (error) {
+        const detail = error;
+        throw new Error(`${label} failed: ${detail.stderr?.trim() || detail.message}`, { cause: error });
+    }
+}
+async function prepareArchive() {
+    const temporary = await mkdtemp(join(tmpdir(), 'canon-distribution-'));
+    try {
+        let runtime = join(packageRoot, 'lib');
+        if (existsSync(join(packageRoot, 'src', 'cli.ts'))) {
+            // Compile only Canon's own source with its known build script. Isolate output so
+            // downloading cannot replace lib/ beneath another running command or test.
+            const workspace = join(temporary, 'build');
+            await mkdir(join(workspace, 'scripts'), { recursive: true });
+            await copyRuntime(join(packageRoot, 'src'), join(workspace, 'src'));
+            await copyFile(join(packageRoot, 'scripts', 'build.mjs'), join(workspace, 'scripts', 'build.mjs'));
+            let compiler;
+            try {
+                compiler = dirname(require.resolve('typescript/package.json'));
+            }
+            catch {
+                throw new Error('Preparing a Canon checkout download requires its TypeScript development dependency. Install the Canon checkout dependencies first.');
+            }
+            await mkdir(join(workspace, 'node_modules'), { recursive: true });
+            await symlink(compiler, join(workspace, 'node_modules', 'typescript'), 'junction');
+            await run(process.execPath, [join(workspace, 'scripts', 'build.mjs')], workspace, temporary, 'Canon runtime compilation');
+            runtime = join(workspace, 'lib');
+        }
+        const staging = join(temporary, 'package');
+        await mkdir(join(staging, 'bin'), { recursive: true });
+        await copyRuntime(join(packageRoot, 'bin', 'canon.js'), join(staging, 'bin', 'canon.js'));
+        await copyRuntime(runtime, join(staging, 'lib'));
+        await copyRuntime(join(packageRoot, 'README.md'), join(staging, 'README.md'));
+        for (const name of ['LICENSE', 'THIRD_PARTY_NOTICES.md']) {
+            await copyRuntime(join(packageRoot, name), join(staging, name));
+        }
+        const original = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));
+        const metadata = {};
+        for (const key of ['name', 'version', 'description', 'type', 'engines', 'license', 'homepage', 'repository', 'bugs', 'keywords', 'publishConfig', 'dependencies', 'optionalDependencies', 'peerDependencies', 'peerDependenciesMeta']) {
+            if (original[key] !== undefined)
+                metadata[key] = original[key];
+        }
+        // An explicit staging tree excludes the served design, caller's project, dev
+        // dependencies, lifecycle hooks, npm configuration and checkout-only files.
+        metadata.bin = { canon: 'bin/canon.js' };
+        metadata.files = ['bin', 'lib', 'README.md', 'LICENSE', 'THIRD_PARTY_NOTICES.md'];
+        await writeFile(join(staging, 'package.json'), JSON.stringify(metadata, null, 2) + '\n');
+        const userConfig = join(temporary, 'user.npmrc');
+        const globalConfig = join(temporary, 'global.npmrc');
+        await writeFile(userConfig, '');
+        await writeFile(globalConfig, '');
+        const { stdout } = await run('npm', [
+            'pack', '--ignore-scripts', '--json', '--offline', '--pack-destination', temporary,
+            '--userconfig', userConfig, '--globalconfig', globalConfig, '--cache', join(temporary, 'npm-cache'),
+        ], staging, temporary, 'Canon package preparation');
+        const packed = JSON.parse(stdout);
+        const filename = packed[0]?.filename;
+        if (typeof filename !== 'string' || !/^[a-zA-Z0-9._-]+\.tgz$/.test(filename)) {
+            throw new Error('npm pack did not return a valid Canon archive filename.');
+        }
+        return await readFile(join(temporary, filename));
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+/** Prepare lazily, share concurrent downloads, and allow a retry after preparation fails. */
+export function getCanonPackage() {
+    archive ??= prepareArchive().catch((error) => {
+        archive = undefined;
+        throw error;
+    });
+    return archive;
+}