flawless-ui-ux 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+## 0.2.0
+
+### Added
+
+- Native CLI install command for the bundled skill, without a repository checkout or Bash.
+- Codex, OpenCode, and both-agent selection, global installation with CODEX_HOME/XDG_CONFIG_HOME support, and explicit project-local installation.
+- Preflight of all selected destinations, preservation of existing files/directories/links, project-boundary checks, and cleanup of newly created skill directories after copy failures.
+- Text/JSON installation reports and package-level installation tests under Node and Bun.
+
+### Changed
+
+- Made npm, pnpm, and Bun skill installation the primary README setup path; retained the Bash installer as an alternative.
+
+## 0.1.1
+
+### Fixed
+
+- Added a black (#000000) background to the README logo so the white wordmark remains readable on light pages.
+- Updated the README image URL to use the matching published package asset.
+
 ## 0.1.0
 
 Initial public release, consolidating the pre-release development iterations.

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/flawless-ui-ux@0.1.0/docs/assets/logo.svg" alt="flawless-ui-ux" width="334" height="80">
+  <img src="https://cdn.jsdelivr.net/npm/flawless-ui-ux@0.1.1/docs/assets/logo.svg" alt="flawless-ui-ux" width="334" height="80">
 </p>
 
 <p align="center">Design interfaces around the product. Refine them against the result.</p>
@@ -8,32 +8,40 @@ flawless-ui-ux helps coding agents create, redesign, and refine web interfaces w
 
 ## Setup
 
-From your project directory, choose your package manager. The CLI requires **Node 22.12+**.
+Choose your package manager to install the skill for **Codex and OpenCode globally**. The CLI requires **Node 22.12+**; no checkout or Bash is needed.
 
 ```bash
-npx flawless-ui-ux@latest --help
-pnpm dlx flawless-ui-ux@latest --help
-bunx flawless-ui-ux@latest --help
+npx flawless-ui-ux@latest install
+pnpm dlx flawless-ui-ux@latest install
+bunx flawless-ui-ux@latest install
 ```
 
-The examples below use `npx`. Replace it with `pnpm dlx` or `bunx` to use the same operations. These commands run the CLI; connect the skill separately to use design guidance in your agent.
+Run one of these commands. The examples below use `npx`; replace it with `pnpm dlx` or `bunx` to use the same operations.
 
-### Connect your coding agent
+### Choose an agent and scope
 
-From a checkout of this repository, install the skill for your agent:
+For a specific agent, or a project-local installation:
 
 ```bash
-bash ./install.sh --codex
-bash ./install.sh --opencode
+npx flawless-ui-ux install --codex
+npx flawless-ui-ux install --opencode --project .
 ```
 
-Use `--all-agents` for both. To install only in a project, run the following from that project's directory:
+The default is both agents globally. Use `--codex`, `--opencode`, or `--all-agents` to select targets. `--project <directory>` installs only in that project; `--global` makes the default scope explicit. Start a new agent session if needed for discovery.
+
+Existing installations are never overwritten, including links and local changes. All selected destinations are checked before copying. Review or remove an existing installation yourself before reinstalling. Global paths honor `CODEX_HOME` and `XDG_CONFIG_HOME`; project paths are `.agents/skills/flawless-ui-ux` for Codex and `.opencode/skills/flawless-ui-ux` for OpenCode.
+
+<details>
+<summary>Alternative: install from a checkout with Bash</summary>
 
 ```bash
-bash /path/to/flawless-ui-ux/install.sh --all-agents --project
+bash ./install.sh --codex
+bash ./install.sh --opencode
 ```
 
-Existing installations are preserved. On Windows, use Git Bash or WSL. Start a new agent session if needed for discovery.
+Use `--all-agents` for both. For project-local installation, run `bash /path/to/flawless-ui-ux/install.sh --all-agents --project` from the target project's directory. On Windows, the Bash alternative requires Git Bash or WSL.
+
+</details>
 
 ## Use the skill
 

package/bin/flawless-ui-ux.js

@@ -3,6 +3,7 @@ import { parse } from '../src/options.js';
 import { context } from '../src/context.js';
 import { inspect } from '../src/inspect.js';
 import { verify } from '../src/verify.js';
+import { install } from '../src/install.js';
 import { VERSION } from '../src/shared.js';
 
 const args = process.argv.slice(2);
@@ -10,21 +11,26 @@ try {
   const { operation, options } = parse([...args]);
   if (operation === 'version') console.log(VERSION);
   else if (operation === 'help') console.log(`flawless-ui-ux ${VERSION}
+  install [--codex | --opencode | --all-agents] [--global | --project DIR]
+          [--format text|json]
   context [--project DIR] [--format text|json]
   inspect [--project DIR] --source FILE [--source FILE ...] [--url URL]
           [--selector CSS] [--viewport WIDTHxHEIGHT ...] [--output NEW_DIR]
           [--timeout MS] [--browser-executable FILE] [--format text|json]
   verify RUN_JSON [--output NEW_DIR] [--browser-executable FILE] [--format text|json]
 
+install defaults to both agents globally. Existing installations are preserved.
 inspect requires a source or URL. Defaults: 1440x900 and 390x844, 15000 ms.
-No server startup, browser download, source edits, or form submission.
+Inspection does not start servers, download browsers, edit sources, or submit forms.
 FLAWLESS_BROWSER_EXECUTABLE explicitly selects an installed Chromium executable.
 Exit codes: 0 completed; 1 confirmed errors; 2 invalid/incomplete.`);
   else {
-    const report = await ({ context, inspect, verify }[operation])(options);
+    const report = await ({ install, context, inspect, verify }[operation])(options);
     if (options.format === 'json') console.log(JSON.stringify(report, null, 2));
     else {
-      console.log(`${operation}: ${report.project}\nCoverage: ${JSON.stringify(report.coverage)} (${report.completion})`);
+      if (operation === 'install') {
+        for (const target of report.installations) console.log(`Installed flawless-ui-ux for ${target.agent} (${target.scope}): ${target.path}`);
+      } else console.log(`${operation}: ${report.project}\nCoverage: ${JSON.stringify(report.coverage)} (${report.completion})`);
       for (const f of report.findings) console.log(`[${f.status}/${f.severity}] ${f.checkId} ${f.target}: ${f.observation}\n  ${f.recommendation}`);
       if (report.operation === 'context') console.log(JSON.stringify({ sources: report.sources, missing: report.missing, saved: report.saved, decisions: report.decisions }, null, 2));
       if (report.comparison) console.log(`Comparison: ${JSON.stringify(report.comparison)}`);

package/docs/assets/logo.svg

@@ -1,4 +1,5 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="334" height="80" viewBox="0 0 334 80" role="img" aria-labelledby="title"><title id="title">flawless-ui-ux</title>
+  <rect width="334" height="80" fill="#000000"/>
   <g transform="translate(20 20) scale(1.666667)"><path d="M4 20l1-5L16 4a2.83 2.83 0 0 1 4 4L9 19l-5 1Z" fill="#0ce491" stroke="#0ce491" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round"/></g>
   <g fill="#ffffff" transform="translate(72 52) scale(0.018 -0.018)">
     <path transform="translate(0 0)" d="M679 933L679 1080L969 1080L969 933ZM243 0L243 1139Q243 1180 246.5 1224Q250 1268 264.5 1309.5Q279 1351 311 1386Q348 1426 392 1444Q436 1462 481.5 1466Q527 1470 568 1470L705 1470L705 1322L578 1322Q499 1322 460 1283Q421 1244 421 1167L421 0ZM60 933L60 1080L705 1080L705 933ZM954 0L954 1470L1132 1470L1132 0Z"/>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flawless-ui-ux",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A UI/UX skill and local inspection CLI for coding agents to build and refine product-specific interfaces.",
   "type": "module",
   "license": "MIT",

package/skills/flawless-ui-ux/references/inspection.md

@@ -1,6 +1,6 @@
 # Executable inspection
 
-Use the local CLI when its executable or checkout is available. The skill installer copies instructions only; do not assume a registry package exists or install dependencies during review. Otherwise use available host tools and state which checks remain unperformed.
+Use the CLI when its executable, package runner, or checkout is available. Its install operation copies the bundled agent instructions; running context, inspect, or verify does not install the skill. Do not change installation or dependencies during a review unless authorized. Otherwise use available host tools and state which checks remain unperformed.
 
 Replace `flawless-ui-ux` below with `node /known/checkout/bin/flawless-ui-ux.js` when using a checkout. Use the actual project, running server URL/port, and affected sources:
 

package/src/install.js

@@ -0,0 +1,94 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { projectRoot, within, VERSION } from './shared.js';
+
+const skillName = 'flawless-ui-ux';
+const bundledSkill = fileURLToPath(new URL('../skills/flawless-ui-ux/', import.meta.url));
+
+// Resolve the nearest existing parent before writing. Project installs cannot
+// escape through an existing directory symlink or junction.
+async function destinationPath(destination, project) {
+  try {
+    await fs.lstat(destination);
+    throw new Error(`Installation already exists: ${destination}`);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  let parent = path.dirname(destination);
+  while (true) {
+    try {
+      await fs.lstat(parent);
+      if (!(await fs.stat(parent)).isDirectory()) throw new Error(`Installation parent is not a directory: ${parent}`);
+      const real = await fs.realpath(parent);
+      if (project && !within(project, real)) throw new Error(`Installation parent escapes the project: ${parent}`);
+      return path.join(real, path.relative(parent, destination));
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      // An existing broken link is a conflict, not a missing parent to create.
+      try { await fs.lstat(parent); throw new Error(`Installation parent is a broken link: ${parent}`); }
+      catch (linkError) { if (linkError.code !== 'ENOENT') throw linkError; }
+      const next = path.dirname(parent);
+      if (next === parent) throw new Error(`No usable installation parent: ${destination}`);
+      parent = next;
+    }
+  }
+}
+
+async function rollback(created) {
+  const errors = [];
+  for (const entry of [...created].reverse()) {
+    try {
+      const current = await fs.lstat(entry.path);
+      const real = await fs.realpath(entry.path);
+      // Recursive removal is limited to the exact directory allocated by this
+      // invocation, with its identity unchanged and no root symlink followed.
+      if (!current.isDirectory() || current.isSymbolicLink() || real !== entry.path ||
+          current.dev !== entry.device || current.ino !== entry.inode ||
+          path.basename(real) !== skillName || !within(path.dirname(entry.path), real)) {
+        throw new Error('Directory identity changed; manual cleanup is required.');
+      }
+      await fs.rm(real, { recursive: true, force: true });
+    } catch (error) { errors.push(`${entry.path}: ${error.message}`); }
+  }
+  return errors;
+}
+
+export async function install(options, runtime = {}) {
+  const env = runtime.env || process.env;
+  const home = runtime.home || os.homedir();
+  const project = options.project ? await projectRoot(options.project) : null;
+  const agent = options.agent || 'all';
+  if (!['all', 'codex', 'opencode'].includes(agent)) throw new Error('Unknown installation agent.');
+  if (!(await fs.stat(path.join(bundledSkill, 'SKILL.md'))).isFile()) throw new Error('The package does not contain an installable skill.');
+  const entries = await fs.readdir(bundledSkill);
+  const candidates = [
+    { agent: 'codex', path: project ? path.join(project, '.agents', 'skills', skillName) : path.resolve(env.CODEX_HOME || path.join(home, '.codex'), 'skills', skillName) },
+    { agent: 'opencode', path: project ? path.join(project, '.opencode', 'skills', skillName) : path.resolve(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'opencode', 'skills', skillName) },
+  ].filter(target => agent === 'all' || target.agent === agent);
+  // Preflight every target before creating any installation directories.
+  const targets = [];
+  for (const candidate of candidates) targets.push({ ...candidate, path: await destinationPath(candidate.path, project) });
+  if (targets.length === 2 && (within(targets[0].path, targets[1].path) || within(targets[1].path, targets[0].path))) throw new Error('Agent installation destinations overlap. Check CODEX_HOME and XDG_CONFIG_HOME.');
+  const created = [];
+  try {
+    for (const target of targets) {
+      await fs.mkdir(path.dirname(target.path), { recursive: true });
+      // Exclusive mkdir also preserves a destination created after preflight.
+      await fs.mkdir(target.path);
+      const identity = await fs.lstat(target.path);
+      created.push({ path: target.path, device: identity.dev, inode: identity.ino });
+      for (const entry of entries) await fs.cp(path.join(bundledSkill, entry), path.join(target.path, entry), { recursive: true, force: false, errorOnExist: true, verbatimSymlinks: true });
+    }
+  } catch (error) {
+    const cleanup = await rollback(created);
+    throw new Error(`Installation failed: ${error.message}${cleanup.length ? ` Cleanup incomplete: ${cleanup.join('; ')}` : ' Newly created skill directories were removed; empty parent directories may remain.'}`);
+  }
+  return {
+    schemaVersion: 1, toolVersion: VERSION, operation: 'install', project,
+    completion: 'complete', coverage: { installation: 'completed' },
+    installations: targets.map(target => ({ ...target, scope: project ? 'project' : 'global' })),
+    findings: [], limits: [], exitCode: 0,
+  };
+}

package/src/options.js

@@ -21,20 +21,30 @@ export function parse(argv) {
   const options = { project: '.', sources: [], viewports: [], timeout: 15000, format: 'text' };
   if (['--help', '-h', undefined].includes(operation)) return { operation: 'help', options };
   if (operation === '--version') return { operation: 'version', options };
-  if (!['context', 'inspect', 'verify'].includes(operation)) throw new Error(`Unknown operation: ${operation}`);
+  if (!['install', 'context', 'inspect', 'verify'].includes(operation)) throw new Error(`Unknown operation: ${operation}`);
+  if (argv.length === 1 && ['--help', '-h'].includes(argv[0])) return { operation: 'help', options };
+  if (operation === 'install') { options.project = undefined; options.agent = 'all'; }
   if (operation === 'verify') {
     options.baseline = argv.shift();
     if (!options.baseline || options.baseline.startsWith('--')) throw new Error('verify requires a run.json path.');
   }
   const seen = new Set();
-  const allowed = operation === 'context' ? ['project', 'format'] : operation === 'verify' ? ['output', 'format', 'browser-executable'] : ['project', 'source', 'url', 'selector', 'viewport', 'output', 'format', 'timeout', 'browser-executable'];
+  const allowed = operation === 'install' ? ['codex', 'opencode', 'all-agents', 'global', 'project', 'format'] : operation === 'context' ? ['project', 'format'] : operation === 'verify' ? ['output', 'format', 'browser-executable'] : ['project', 'source', 'url', 'selector', 'viewport', 'output', 'format', 'timeout', 'browser-executable'];
   while (argv.length) {
     const flag = argv.shift();
     if (!flag.startsWith('--') || !allowed.includes(flag.slice(2))) throw new Error(`Unknown option: ${flag}`);
-    const name = flag.slice(2), value = argv.shift();
-    if (!value || value.startsWith('--')) throw new Error(`Missing value for ${flag}`);
+    const name = flag.slice(2);
     if (seen.has(name) && !['source', 'viewport'].includes(name)) throw new Error(`Repeated option: ${flag}`);
+    if (operation === 'install' && ['codex', 'opencode', 'all-agents'].includes(name)) {
+      if (['codex', 'opencode', 'all-agents'].some(agent => seen.has(agent))) throw new Error('Select one agent option, or use --all-agents for both.');
+      options.agent = name === 'all-agents' ? 'all' : name;
+      seen.add(name);
+      continue;
+    }
     seen.add(name);
+    if (operation === 'install' && name === 'global') continue;
+    const value = argv.shift();
+    if (!value || value.startsWith('--')) throw new Error(`Missing value for ${flag}`);
     if (name === 'source') options.sources.push(value);
     else if (name === 'viewport') {
       const match = /^(\d+)x(\d+)$/.exec(value);
@@ -43,6 +53,7 @@ export function parse(argv) {
     } else options[{ 'browser-executable': 'browserExecutable' }[name] || name] = name === 'timeout' ? Number(value) : value;
   }
   if (!['text', 'json'].includes(options.format)) throw new Error('Format must be text or json.');
+  if (operation === 'install' && seen.has('global') && seen.has('project')) throw new Error('Choose --global or --project, not both.');
   if (operation === 'inspect' && options.url) options.browserExecutable ||= process.env.FLAWLESS_BROWSER_EXECUTABLE;
   if (operation === 'inspect') validateInspection(options);
   return { operation, options };