frakment 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,190 @@
+Frakment License
+Version 1.0
+
+Copyright (c) 2026 hanshapd <https://github.com/hanshapd>
+
+This is a source-available license. It is NOT an open-source license
+as defined by the Open Source Initiative (OSI).
+
+In short:
+
+  - Use Frakment freely for personal, educational, and non-commercial
+    purposes. Just keep the attribution.
+
+  - Use Frakment commercially only after you get one pull request
+    merged into the main repository. That is the only path.
+
+  - Always keep the attribution. Always mark modifications.
+
+====================================================================
+1. DEFINITIONS
+====================================================================
+
+"Software" means the source code, components, CLI, MCP server, agent
+skills, documentation, and any associated files in this repository,
+whether used in original or modified form.
+
+"Personal Use" means use by an individual for personal projects,
+learning, experimentation, hobby work, or internal tools that do not
+generate revenue.
+
+"Educational Use" means use by students, teachers, or institutions
+for teaching, coursework, academic research, or non-commercial
+educational activities.
+
+"Commercial Use" means any use that:
+
+  (a) is part of a product, service, or website that generates revenue
+      directly or indirectly (including ads, subscriptions, paid
+      features, consulting, or paid support);
+  (b) is deployed in production by a for-profit entity; or
+  (c) is used to build something that is sold, licensed, or monetized
+      in any form.
+
+"Qualifying Contribution" means a pull request that has been
+reviewed and merged into the main branch of
+github.com/hanshapd/frakment, where all of the following are true:
+
+  (a) The commit author is you (your GitHub username or email is
+      recorded in the commit metadata).
+  (b) The pull request makes at least one substantive change: fixes a
+      bug, adds a feature, adds or corrects documentation, adds a
+      test, translates content, or fixes a typo.
+  (c) The pull request has not been reverted within 30 days of being
+      merged.
+
+There is no minimum number of lines changed. A single-line typo fix
+qualifies. A documentation clarification qualifies. A test addition
+qualifies.
+
+A pull request that was closed without merging does NOT qualify. A
+pull request that was merged and later reverted within 30 days does
+NOT qualify.
+
+====================================================================
+2. GRANT OF RIGHTS
+====================================================================
+
+Subject to the terms of this license, you are granted permission to:
+
+  (a) View, read, and study the source code.
+  (b) Fork, clone, and copy the repository.
+  (c) Modify the source code.
+  (d) Distribute the original or modified version.
+
+These rights apply without additional conditions for Personal Use and
+Educational Use, provided you satisfy the Attribution Requirements in
+Section 3.
+
+These rights apply for Commercial Use only after you have made a
+Qualifying Contribution, in addition to the Attribution Requirements.
+
+====================================================================
+3. ATTRIBUTION REQUIREMENTS (ALWAYS)
+====================================================================
+
+Any use, copy, modification, or distribution of the Software, in
+whole or in part, for Personal, Educational, or Commercial Use, must:
+
+  (a) Include the following attribution in the README, documentation,
+      footer, or another reasonably visible user-facing location:
+
+        Based on Frakment by hanshapd
+        https://github.com/hanshapd/frakment
+
+  (b) Include this LICENSE file unmodified in all copies and
+      derivative works.
+
+  (c) Clearly mark any modified versions as modified, with a brief
+      description of the changes (e.g., in a CHANGELOG or README).
+
+====================================================================
+4. COMMERCIAL USE REQUIREMENT
+====================================================================
+
+Before using the Software for any Commercial Use, you (or the legal
+entity you represent) must have made one Qualifying Contribution as
+defined in Section 1. This is the only path to Commercial Use.
+
+--------------------------------------------------------------------
+4.1  SCOPE OF SATISFACTION
+--------------------------------------------------------------------
+
+Once a Qualifying Contribution has been made, the requirement is
+satisfied permanently for:
+
+  - the individual who made the contribution, OR
+  - the legal entity (company, organization, or team) on whose
+    behalf the contribution was made,
+
+for all future Commercial Use of the Software by that individual or
+entity. No further contributions are required for future commercial
+use by the same party.
+
+--------------------------------------------------------------------
+4.2  EVIDENCE ON REQUEST
+--------------------------------------------------------------------
+
+If hanshapd requests proof that the Commercial Use requirement has
+been satisfied, you must provide, within 30 days, a link to the
+merged pull request on GitHub.
+
+Refusal or failure to provide evidence on request voids the
+permission for Commercial Use until evidence is provided.
+
+--------------------------------------------------------------------
+4.3  NO REQUIREMENT FOR NON-COMMERCIAL USE
+--------------------------------------------------------------------
+
+Personal Use and Educational Use do NOT require a Qualifying
+Contribution. Attribution (Section 3) is the only requirement for
+those uses.
+
+====================================================================
+5. RESTRICTIONS
+====================================================================
+
+You may not:
+
+  (a) Remove, hide, or alter copyright notices or the attribution
+      required by Section 3.
+  (b) Claim authorship of this Software or of any derivative work.
+  (c) Use the names "Frakment", "frakment", or "hanshapd", or any
+      associated logos or branding, to endorse or promote derivative
+      works without prior written permission.
+  (d) Sublicense this Software under different terms. Any party that
+      receives a copy from you does so subject to this same license.
+
+====================================================================
+6. NO TRADEMARK LICENSE
+====================================================================
+
+This license does not grant any rights to use the names "Frakment",
+"frakment", or "hanshapd", or any associated logos or marks, except
+as strictly necessary for the attribution described in Section 3.
+
+====================================================================
+7. WARRANTY
+====================================================================
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+NON-INFRINGEMENT.
+
+IN NO EVENT SHALL THE AUTHOR OR COPYRIGHT HOLDER BE LIABLE FOR ANY
+CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+====================================================================
+8. ACCEPTANCE
+====================================================================
+
+By accessing, using, copying, modifying, or distributing this project,
+you agree to be bound by the terms above. If you do not agree, you are
+not granted permission to use this project and must delete all copies
+in your possession.
+
+For permission requests or questions about this license, contact
+hanshapd on GitHub: https://github.com/hanshapd

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# frakment CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Monochrome design system and component registry CLI.
+
+## Requirements
+
+- Node.js >= 22.12.0
+- Tailwind CSS v4 (`@import "tailwindcss";` in your `globals.css`)
+
+## Usage
+
+### `frakment init`
+
+```bash
+npx frakment@latest init
+```
+
+What it does:
+
+1. Writes `components.json` at project root (CLI config)
+2. Injects the theme block into `globals.css` between `/* ==== FRAKMENT THEME START/END ==== */` markers (design tokens + 9 `@utility` + `.dark` + `@custom-variant dark`)
+3. Preserves anything outside the markers — your `@import` statements, overrides, and custom CSS stay untouched
+4. Creates `lib/utils.ts` (the `cn` helper) if missing
+5. Installs 6 dependencies: `clsx`, `tailwind-merge`, `class-variance-authority`, `radix-ui`, `lucide-react`, `motion`
+
+**Idempotent.** Safe to re-run:
+
+- Existing `components.json` is preserved unless you choose to overwrite
+- Marker block is replaced in place (no duplicates)
+- Legacy inline theme blocks (from older `init` versions) are auto-migrated
+
+### `frakment add <component>`
+
+```bash
+npx frakment@latest add button
+```
+
+Fetches the component (plus all `registryDependencies` recursively) from the registry, writes all files, and installs any missing npm dependencies.
+
+Flags:
+
+- `--registry <url>` — override the registry URL (default: from `components.json`)
+- `--overwrite` — overwrite existing files without prompting
+
+### `frakment list`
+
+```bash
+npx frakment@latest list
+```
+
+Lists all available components from the registry.
+
+## Registry
+
+The default registry URL is written to `components.json` during `init`. If the public registry is not live yet, pass `--registry <url>` explicitly:
+
+```bash
+npx frakment@latest add badge --registry http://localhost:8765
+```
+
+## Troubleshooting
+
+### "Frakment requires Tailwind v4"
+
+Your `globals.css` must contain `@import "tailwindcss";`. Frakment relies on Tailwind v4 features (`@theme`, `@utility`, `@custom-variant`). Tailwind v3 is not supported.
+
+### "Could not find globals.css"
+
+The CLI looks for one of:
+
+- `app/globals.css`
+- `src/app/globals.css`
+- `styles/globals.css`
+- `src/styles/globals.css`
+
+If none exist, create one with at minimum:
+
+```css
+@import "tailwindcss";
+```
+
+### `src/` directory projects
+
+If your `globals.css` lives at `src/app/globals.css`, component files are written to `src/components/`, `src/lib/`, `src/hooks/`. Binary assets under `public/` are written to `public/` at the project root (Next.js serves `public/` from the root regardless of `src/` layout).
+
+## License
+
+Source-available. See [LICENSE](./LICENSE). Commercial use requires at least one merged pull request to [arrafipd/frakment](https://github.com/arrafipd/frakment).

package/bin/index.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import pc from "picocolors";
+
+import { add } from "../src/commands/add.js";
+import { init } from "../src/commands/init.js";
+import { list } from "../src/commands/list.js";
+
+const __dirname = import.meta.dirname;
+const pkg = JSON.parse(
+  readFileSync(path.resolve(__dirname, "../package.json"), "utf-8")
+);
+
+const program = new Command();
+
+program
+  .name("frakment")
+  .description("Monochrome design system and component registry")
+  .version(pkg.version)
+  .addHelpText(
+    "after",
+    `
+Examples:
+  ${pc.dim("$ frakment init")}
+  ${pc.dim("$ frakment add status-chip")}
+  ${pc.dim("$ frakment list")}
+`
+  );
+
+program
+  .command("init")
+  .description("Initialize frakment in your project")
+  .action(init);
+
+program
+  .command("add <component>")
+  .description("Add a component from the frakment registry")
+  .option("--registry <url>", "Custom registry URL")
+  .option("--overwrite", "Overwrite existing files", false)
+  .action(add);
+
+program
+  .command("list")
+  .description("List available components")
+  .option("--registry <url>", "Custom registry URL")
+  .action(list);
+
+program.parse();

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "frakment",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "CLI and design system for the frakment component registry",
+  "keywords": [
+    "components",
+    "frakment",
+    "monochrome",
+    "registry",
+    "tailwindcss"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "arrafipd (https://github.com/arrafipd)",
+  "type": "module",
+  "bin": {
+    "frakment": "./bin/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "commander": "^15.0.0",
+    "execa": "^10.2.1",
+    "picocolors": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}

package/src/commands/add.js

@@ -0,0 +1,142 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import * as p from "@clack/prompts";
+import { execa } from "execa";
+import pc from "picocolors";
+
+import { detectPackageManager, findProjectRoot } from "../utils/detect.js";
+
+async function fetchComponent(name, registryUrl, s) {
+  s.start(`fetching ${name}`);
+  try {
+    const res = await fetch(`${registryUrl}/${name}.json`);
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}`);
+    }
+    const payload = await res.json();
+    s.stop(`${pc.green("✓")} fetched ${name}`);
+    return payload;
+  } catch {
+    s.stop(`${pc.red("✗")} ${name} not found in registry`);
+    process.exit(1);
+  }
+}
+
+async function writeFileSafely(file, cwd, options) {
+  const targetPath = path.join(cwd, file.path);
+  if (existsSync(targetPath) && !options.overwrite) {
+    const overwrite = await p.confirm({
+      initialValue: false,
+      message: `${file.path} already exists. Overwrite?`,
+    });
+    if (p.isCancel(overwrite) || !overwrite) {
+      p.log.info(`skipped ${file.path}`);
+      return;
+    }
+  }
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  const output =
+    file.encoding === "base64"
+      ? Buffer.from(file.content, "base64")
+      : file.content.replaceAll("\r\n", "\n");
+  await writeFile(targetPath, output);
+  p.log.success(file.path);
+}
+
+export async function add(componentName, options) {
+  p.intro(`${pc.dim("frakment")} add ${pc.bold(componentName)}`);
+
+  let cwd;
+  try {
+    cwd = findProjectRoot(process.cwd());
+  } catch (error) {
+    p.outro(pc.red("error ") + error.message);
+    process.exit(1);
+  }
+
+  const configPath = path.join(cwd, "components.json");
+  if (!existsSync(configPath)) {
+    p.outro(
+      `${pc.red(
+        "error "
+      )}components.json not found. Run \`frakment init\` first.`
+    );
+    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, "");
+  const s = p.spinner();
+
+  // 1. Recursively fetch the component and its registryDependencies
+  const queue = [componentName];
+  const fetched = new Map();
+  const npmDeps = new Set();
+
+  while (queue.length) {
+    const name = queue.shift();
+    if (fetched.has(name)) {
+      continue;
+    }
+    const payload = await fetchComponent(name, registryUrl, s);
+    fetched.set(name, payload);
+    for (const d of payload.dependencies ?? []) {
+      npmDeps.add(d);
+    }
+    for (const d of payload.registryDependencies ?? []) {
+      if (!fetched.has(d)) {
+        queue.push(d);
+      }
+    }
+  }
+
+  // 2. Write registry deps first (imports resolve), then main component
+  // Detect src/ layout: component files go under src/, but public/ assets
+  // stay at project root (Next.js serves public/ from root regardless of src/).
+  const isSrcLayout = config.tailwind?.css?.startsWith("src/") ?? false;
+  const resolveTargetPath = (p) => {
+    if (!isSrcLayout) {
+      return p;
+    }
+    if (p.startsWith("public/")) {
+      return p;
+    }
+    return `src/${p}`;
+  };
+
+  const order = [...fetched.keys()].filter((n) => n !== componentName);
+  order.push(componentName);
+  for (const name of order) {
+    for (const file of fetched.get(name).files ?? []) {
+      const targetFile = { ...file, path: resolveTargetPath(file.path) };
+      await writeFileSafely(targetFile, cwd, options);
+    }
+  }
+
+  // 3. Install npm dependencies
+  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]);
+    if (missing.length > 0) {
+      s.start(`installing ${missing.join(", ")}`);
+      const pm = detectPackageManager(cwd);
+      try {
+        const args =
+          pm === "npm" ? ["install", ...missing] : ["add", ...missing];
+        await execa(pm, args, { cwd, stdio: "ignore" });
+        s.stop(`${pc.green("✓")} installed ${missing.length} package(s)`);
+      } catch (error) {
+        s.stop(`${pc.red("✗")} failed to install dependencies`);
+        p.log.warn(error.message);
+      }
+    }
+  }
+
+  p.outro(`${pc.green("✓")} ${componentName} added`);
+}