frakment 0.0.6 → 0.1.0

package/README.md

@@ -58,6 +58,9 @@ Flags:
 - `--registry <url>` — override the registry URL (default: from `components.json`)
 - `--overwrite` — overwrite existing files without prompting
 
+- `--dry-run` — show planned file and dependency changes without changing the project
+- `--skip-dependencies` — write component files without installing missing npm dependencies
+
 ### `frakment list`
 
 ```bash

package/bin/index.js

@@ -37,7 +37,12 @@ program
 program
   .command("add <component>")
   .description("Add a component from the frakment registry")
+  .option(
+    "--dry-run",
+    "Show planned file and dependency changes without writing"
+  )
   .option("--registry <url>", "Custom registry URL")
+  .option("--skip-dependencies", "Do not install missing npm dependencies")
   .option("--overwrite", "Overwrite existing files", false)
   .action(add);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frakment",
-  "version": "0.0.6",
+  "version": "0.1.0",
   "description": "CLI and design system for the frakment component registry",
   "keywords": [
     "components",

package/src/commands/add.js

@@ -1,5 +1,6 @@
+import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
 import path from "node:path";
 
 import chalk from "chalk";
@@ -10,22 +11,191 @@ import prompts from "prompts";
 import { detectPackageManager, findProjectRoot } from "../utils/detect.js";
 import { logger } from "../utils/logger.js";
 
+const COMPONENT_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const DEPENDENCY_PATTERN =
+  /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:@[0-9A-Za-z*~^<>=|.+_-]+)?$/u;
+const MAX_REGISTRY_PAYLOAD_BYTES = 10 * 1024 * 1024;
+
+const isRecord = (value) =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const canonicalize = (value) => {
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalize).join(",")}]`;
+  }
+  if (isRecord(value)) {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+};
+
+const createIntegrity = (payload) =>
+  `sha256:${createHash("sha256")
+    .update(canonicalize(payload), "utf8")
+    .digest("hex")}`;
+
+const assertComponentName = (name) => {
+  if (typeof name !== "string" || !COMPONENT_NAME_PATTERN.test(name)) {
+    throw new Error(`Invalid component name: ${String(name)}`);
+  }
+};
+
+const assertDependency = (dependency) => {
+  if (typeof dependency !== "string" || !DEPENDENCY_PATTERN.test(dependency)) {
+    throw new Error(
+      `Invalid dependency in registry payload: ${String(dependency)}`
+    );
+  }
+};
+
+const getDependencyName = (dependency) => {
+  if (dependency.startsWith("@")) {
+    return dependency.slice(0, dependency.indexOf("@", 1));
+  }
+  return dependency.split("@")[0];
+};
+
+const hasDependencyVersion = (dependency) =>
+  dependency.lastIndexOf("@") > (dependency.startsWith("@") ? 0 : -1);
+
+const isBase64 = (value) =>
+  /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(
+    value
+  );
+
+export const validateRegistryPayload = (payload, expectedName) => {
+  if (!isRecord(payload) || payload.name !== expectedName) {
+    throw new Error("Registry payload has an unexpected component name");
+  }
+  if (
+    typeof payload.integrity !== "string" ||
+    !/^sha256:[a-f0-9]{64}$/u.test(payload.integrity)
+  ) {
+    throw new Error("Registry payload has invalid integrity metadata");
+  }
+  if (!Array.isArray(payload.files) || payload.files.length === 0) {
+    throw new Error("Registry payload must include at least one file");
+  }
+  if (payload.files.length > 100) {
+    throw new Error("Registry payload has too many files");
+  }
+
+  for (const file of payload.files) {
+    if (!isRecord(file) || typeof file.path !== "string") {
+      throw new Error("Registry payload contains an invalid file");
+    }
+    if (typeof file.content !== "string") {
+      throw new Error(`Registry file ${file.path} has invalid content`);
+    }
+    if (file.encoding !== undefined && file.encoding !== "base64") {
+      throw new Error(`Registry file ${file.path} has an unsupported encoding`);
+    }
+    if (file.encoding === "base64" && !isBase64(file.content)) {
+      throw new Error(`Registry file ${file.path} has invalid base64 content`);
+    }
+  }
+
+  if (
+    !(
+      Array.isArray(payload.dependencies ?? []) &&
+      Array.isArray(payload.registryDependencies ?? [])
+    )
+  ) {
+    throw new Error("Registry payload has invalid dependency lists");
+  }
+  for (const dependency of payload.dependencies ?? []) {
+    assertDependency(dependency);
+  }
+  for (const dependency of payload.registryDependencies ?? []) {
+    assertComponentName(dependency);
+  }
+
+  const { integrity, ...unsignedPayload } = payload;
+  if (integrity !== createIntegrity(unsignedPayload)) {
+    throw new Error("Registry payload integrity check failed");
+  }
+
+  return payload;
+};
+
+const getRegistryUrl = (value) => {
+  const url = new URL(value);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("Registry URL must use HTTP or HTTPS");
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error(
+      "Registry URL must not include credentials, a query, or a fragment"
+    );
+  }
+  return url.href.replace(/\/$/u, "");
+};
+
 async function fetchComponent(name, registryUrl, spinner) {
   try {
-    const res = await fetch(`${registryUrl}/${name}.json`);
+    const res = await fetch(`${registryUrl}/${name}.json`, {
+      signal: AbortSignal.timeout(30_000),
+    });
     if (!res.ok) {
       throw new Error(`HTTP ${res.status}`);
     }
-    const payload = await res.json();
+    const contentLength = Number(res.headers.get("content-length"));
+    if (contentLength > MAX_REGISTRY_PAYLOAD_BYTES) {
+      throw new Error("Registry response is too large");
+    }
+    const raw = await res.text();
+    if (Buffer.byteLength(raw, "utf8") > MAX_REGISTRY_PAYLOAD_BYTES) {
+      throw new Error("Registry response is too large");
+    }
+    const payload = validateRegistryPayload(JSON.parse(raw), name);
     spinner.text = `Fetching ${name}...`;
     return payload;
-  } catch {
-    spinner.fail(`Registry fetch failed for ${name}.`);
+  } catch (error) {
+    spinner.fail(
+      `Registry fetch failed for ${name}: ${error instanceof Error ? error.message : "unknown error"}`
+    );
     process.exit(1);
   }
 }
+
+export async function assertSafePath(cwd, relativePath) {
+  if (typeof relativePath !== "string" || relativePath.length === 0) {
+    throw new Error("Invalid file path in registry payload");
+  }
+  if (relativePath.includes("\0")) {
+    throw new Error(`Null byte in path: ${relativePath}`);
+  }
+  if (path.isAbsolute(relativePath) || /^[a-zA-Z]:/.test(relativePath)) {
+    throw new Error(`Absolute path rejected: ${relativePath}`);
+  }
+  if (relativePath.split(/[\\/]/).some((seg) => seg === "..")) {
+    throw new Error(`Parent traversal rejected: ${relativePath}`);
+  }
+  const root = path.resolve(cwd);
+  const target = path.resolve(root, relativePath);
+  if (target !== root && !target.startsWith(root + path.sep)) {
+    throw new Error(`Path escapes project root: ${relativePath}`);
+  }
+  const realRoot = await realpath(root).catch(() => root);
+  let existingParent = path.dirname(target);
+  while (!existsSync(existingParent)) {
+    existingParent = path.dirname(existingParent);
+  }
+  const realParent = await realpath(existingParent).catch(() => existingParent);
+  if (realParent !== realRoot && !realParent.startsWith(realRoot + path.sep)) {
+    throw new Error(`Symlink escape rejected: ${relativePath}`);
+  }
+  if (existsSync(target) && (await lstat(target)).isSymbolicLink()) {
+    throw new Error(`Symlink target rejected: ${relativePath}`);
+  }
+  return target;
+}
+
 async function writeFileSafely(file, cwd, options) {
-  const targetPath = path.join(cwd, file.path);
+  const targetPath = await assertSafePath(cwd, file.path);
   if (existsSync(targetPath) && !options.overwrite) {
     const { overwrite } = await prompts({
       initial: false,
@@ -64,14 +234,24 @@ export async function add(componentName, options) {
     process.exit(1);
   }
 
-  const configRaw = await readFile(configPath, "utf-8");
-  const config = JSON.parse(configRaw.replace(/^\uFEFF/u, ""));
-  const registryUrl = (options.registry ?? config.registry).replace(/\/$/u, "");
+  let config;
+  let registryUrl;
+  try {
+    assertComponentName(componentName);
+    const configRaw = await readFile(configPath, "utf-8");
+    config = JSON.parse(configRaw.replace(/^\uFEFF/u, ""));
+    registryUrl = getRegistryUrl(options.registry ?? config.registry);
+  } catch (error) {
+    logger.error(
+      error instanceof Error ? error.message : "Invalid configuration."
+    );
+    process.exit(1);
+  }
 
   const registrySpinner = ora("Checking registry").start();
   const queue = [componentName];
   const fetched = new Map();
-  const npmDeps = new Set();
+  const npmDeps = new Map();
 
   while (queue.length) {
     const name = queue.shift();
@@ -81,7 +261,14 @@ export async function add(componentName, options) {
     const payload = await fetchComponent(name, registryUrl, registrySpinner);
     fetched.set(name, payload);
     for (const d of payload.dependencies ?? []) {
-      npmDeps.add(d);
+      const packageName = getDependencyName(d);
+      const existing = npmDeps.get(packageName);
+      if (
+        !existing ||
+        (!hasDependencyVersion(existing) && hasDependencyVersion(d))
+      ) {
+        npmDeps.set(packageName, d);
+      }
     }
     for (const d of payload.registryDependencies ?? []) {
       if (!fetched.has(d)) {
@@ -105,6 +292,31 @@ export async function add(componentName, options) {
   order.push(componentName);
   const written = [];
 
+  const getMissingDependencies = async () => {
+    const pkgPath = path.join(cwd, "package.json");
+    const pkgRaw = await readFile(pkgPath, "utf-8");
+    const pkg = JSON.parse(pkgRaw.replace(/^\uFEFF/u, ""));
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    return [...npmDeps].filter(([packageName]) => !allDeps[packageName]);
+  };
+
+  if (options.dryRun) {
+    for (const name of order) {
+      for (const file of fetched.get(name).files) {
+        const targetPath = resolveTargetPath(file.path);
+        await assertSafePath(cwd, targetPath);
+        logger.log(`Would create ${targetPath}.`);
+      }
+    }
+    const missing = await getMissingDependencies();
+    for (const [, dependency] of missing) {
+      logger.log(`Would install ${dependency}.`);
+    }
+    logger.success("Dry run complete. No files or dependencies were changed.");
+    logger.break();
+    return;
+  }
+
   for (const name of order) {
     for (const file of fetched.get(name).files ?? []) {
       const targetFile = { ...file, path: resolveTargetPath(file.path) };
@@ -124,17 +336,20 @@ export async function add(componentName, options) {
     }
   }
   if (npmDeps.size > 0) {
-    const pkgPath = path.join(cwd, "package.json");
-    const pkgRaw = await readFile(pkgPath, "utf-8");
-    const pkg = JSON.parse(pkgRaw.replace(/^\uFEFF/u, ""));
-    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-    const missing = [...npmDeps].filter((d) => !allDeps[d]);
+    const missing = await getMissingDependencies();
     if (missing.length > 0) {
+      if (options.skipDependencies) {
+        logger.info(`Skipped ${missing.length} dependency installation(s).`);
+        logger.break();
+        return;
+      }
       const s = ora("Installing dependencies").start();
       const pm = detectPackageManager(cwd);
       try {
         const args =
-          pm === "npm" ? ["install", ...missing] : ["add", ...missing];
+          pm === "npm"
+            ? ["install", ...missing.map(([, dependency]) => dependency)]
+            : ["add", ...missing.map(([, dependency]) => dependency)];
         await execa(pm, args, { cwd, stdio: "ignore" });
         s.succeed(`Installed ${missing.length} package(s).`);
       } catch (error) {

package/src/commands/add.test.mjs

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+
+import { assertSafePath, validateRegistryPayload } from "./add.js";
+
+const unsignedPayload = {
+  dependencies: ["@frakment/react@^0.0.3", "motion@^14.10.0"],
+  files: [
+    {
+      content: "export {};\n",
+      path: "components/ui/example.tsx",
+    },
+  ],
+  name: "example",
+  registryDependencies: ["button"],
+};
+
+const payload = {
+  ...unsignedPayload,
+  integrity:
+    "sha256:d75c2cab99c7b025d584adc04eb9b2eb86794f1a51df578f94c74c0eef22634d",
+};
+
+describe("registry payload validation", () => {
+  it("accepts a valid component payload", () => {
+    expect(validateRegistryPayload(payload, "example")).toEqual(payload);
+  });
+
+  it("rejects a component name mismatch", () => {
+    expect(() => validateRegistryPayload(payload, "button")).toThrow(
+      "unexpected component name"
+    );
+  });
+
+  it("rejects invalid dependency specifications", () => {
+    expect(() =>
+      validateRegistryPayload(
+        { ...payload, dependencies: ["file:../malicious-package"] },
+        "example"
+      )
+    ).toThrow(/invalid dependency/i);
+  });
+
+  it("rejects malformed files and registry dependencies", () => {
+    expect(() =>
+      validateRegistryPayload(
+        {
+          ...payload,
+          files: [{ content: "x", encoding: "hex", path: "file.ts" }],
+        },
+        "example"
+      )
+    ).toThrow("unsupported encoding");
+    expect(() =>
+      validateRegistryPayload(
+        { ...payload, registryDependencies: ["../button"] },
+        "example"
+      )
+    ).toThrow("Invalid component name");
+  });
+
+  it("rejects content that does not match the integrity hash", () => {
+    expect(() =>
+      validateRegistryPayload(
+        {
+          ...payload,
+          files: [{ content: "changed", path: "components/ui/example.tsx" }],
+        },
+        "example"
+      )
+    ).toThrow("integrity check failed");
+  });
+});
+
+describe("registry target paths", () => {
+  it("accepts paths within the project root", async () => {
+    await expect(
+      assertSafePath(process.cwd(), "components/ui/button.tsx")
+    ).resolves.toContain("components");
+  });
+
+  it("rejects parent traversal and absolute paths", async () => {
+    await expect(
+      assertSafePath(process.cwd(), "../../outside.txt")
+    ).rejects.toThrow("Parent traversal rejected");
+    await expect(
+      assertSafePath(process.cwd(), "C:\\outside.txt")
+    ).rejects.toThrow("Absolute path rejected");
+  });
+});

package/src/commands/init.js

@@ -140,14 +140,18 @@ export function cn(...inputs: ClassValue[]) {
     await mkdir(path.join(cwd, "lib"), { recursive: true });
     await writeFile(
       path.join(cwd, "lib/animation.ts"),
-      `export const SPRING_SMOOTH = { type: "spring", stiffness: 200, damping: 30 } as const
+      `export const springSoft = { type: "spring", stiffness: 200, damping: 30 } as const
 
-export const EASE_OUT = [0.16, 1, 0.3, 1] as const
-export const EASE_SMOOTH = [0.32, 0.72, 0, 1] as const
-export const EASE_IN_OUT = [0.4, 0, 0.2, 1] as const
+export const easeInOut = [0.4, 0, 0.2, 1] as const
+export const easeInOutQuad = [0.45, 0, 0.55, 1] as const
+export const easeOutExpo = [0.16, 1, 0.3, 1] as const
+export const easeSmoothOut = [0.32, 0.72, 0, 1] as const
 
-export const DURATION_FAST = 0.2
-export const DURATION_SMOOTH = 0.45
+export const durationFast = 0.2
+export const durationNormal = 0.3
+export const durationSlow = 0.45
+
+export const delayTight = 0.02
 `
     );
     s.succeed("Created 1 file:");