clippa 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Dovhosheia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS 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.

package/README.md

@@ -0,0 +1,105 @@
+<p align="center">
+  <img src="docs/assets/app-icon.png" width="96" height="96" alt="Clippa icon">
+</p>
+
+<h1 align="center">Clippa</h1>
+
+<p align="center">
+  A small, private macOS clipboard app built around one shortcut: press Command-Shift-W, choose a clip, paste.
+</p>
+
+<p align="center">
+  <a href="https://vaniawl.github.io/Clippa/">Website</a>
+  ·
+  <a href="https://github.com/Vaniawl/Clippa/releases">Releases</a>
+  ·
+  <a href="#privacy">Privacy</a>
+</p>
+
+<p align="center">
+  <img src="docs/assets/screenshot-panel.svg" alt="Clippa clipboard panel" width="900">
+</p>
+
+## Install Clippa
+
+Install the current GitHub build:
+
+```bash
+npx github:Vaniawl/Clippa
+```
+
+After npm publish, the public install command will be:
+
+```bash
+npx clippa
+```
+
+After it opens, grant Accessibility access when macOS asks. Clippa needs that permission only to paste the selected item into the app where your cursor is already active.
+
+Useful installer options:
+
+```bash
+npx github:Vaniawl/Clippa -- --no-open
+npx github:Vaniawl/Clippa -- --install-dir ~/Applications
+```
+
+You can also download `Clippa.app.zip` from the latest GitHub release, unzip it, move `Clippa.app` to `/Applications`, and open it.
+
+## How It Works
+
+- Runs quietly in the background as a menu-bar app.
+- Press `Command-Shift-W` while your cursor is in a text field.
+- Use `Up` / `Down` to choose a clipboard item.
+- Press `Enter` or click an item to paste it.
+- Press `Esc` or click outside the panel to close it.
+- Stores recent text, links, images, and file references locally on your Mac.
+
+## Privacy
+
+Clippa does not upload clipboard contents, does not use analytics, and does not require an account. Clipboard history is stored only on your Mac and encrypted locally with a per-user AES-GCM key file in Application Support. Clippa does not read or write Keychain items at startup, so locally signed reinstall builds do not trigger Keychain password prompts.
+
+Accessibility permission is only used to confirm there is an editable field under the cursor and to paste the selected clip into that frontmost app.
+
+## Requirements
+
+- macOS 26.0 or newer
+- Xcode 26.6 or newer, only if you want to build from source
+
+## Build From Source
+
+```bash
+git clone https://github.com/Vaniawl/Clippa.git
+cd Clippa
+xcodebuild -project Clippa.xcodeproj -scheme Clippa -destination 'platform=macOS' test
+SMOKE_LAUNCH=1 ./scripts/release.sh
+```
+
+The packaged app is written to:
+
+```bash
+outputs/Clippa.app.zip
+```
+
+## npm Publish
+
+The npm installer package is prepared as `clippa`. Publishing to npm requires an authenticated npm session:
+
+```bash
+npm adduser
+npm publish --access public
+```
+
+## Update From Git
+
+For an existing checkout:
+
+```bash
+git pull origin main
+```
+
+## Production Notes
+
+- Bundle identifier: `com.ivandovhosheia.Clippa`
+- Version: `1.0.0`
+- Release builds use hardened runtime.
+- Recent history is limited to 100 active items and stored only on this Mac.

package/bin/install-clippa.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+
+const { execFileSync } = require("node:child_process");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const https = require("node:https");
+
+const appName = "Clippa";
+const bundleIdentifier = "com.ivandovhosheia.Clippa";
+const localZipPath = path.resolve(__dirname, "../outputs/Clippa.app.zip");
+const packageJson = require("../package.json");
+const defaultZipUrl = "https://github.com/Vaniawl/Clippa/releases/download/v1.0.0/Clippa.app.zip";
+const zipUrl = process.env.CLIPPA_ZIP_URL || defaultZipUrl;
+
+function usage() {
+  console.log(`Install Clippa for macOS.
+
+Usage:
+  npx github:Vaniawl/Clippa
+  npx clippa
+
+Options:
+  --install-dir <path>  Copy Clippa.app into a custom applications folder.
+  --no-open             Install without opening Clippa afterwards.
+  --version             Show installer version.
+  --help                Show this help.
+
+The installer copies Clippa.app to /Applications when possible, otherwise to ~/Applications.
+Press Command-Shift-W in a text field to open Clippa.
+`);
+}
+
+function run(command, args, options = {}) {
+  execFileSync(command, args, { stdio: "inherit", ...options });
+}
+
+function parseArgs(argv) {
+  const options = {
+    help: false,
+    version: false,
+    noOpen: false,
+    installDir: null
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case "--help":
+      case "-h":
+        options.help = true;
+        break;
+      case "--version":
+      case "-v":
+        options.version = true;
+        break;
+      case "--no-open":
+        options.noOpen = true;
+        break;
+      case "--install-dir":
+        index += 1;
+        if (!argv[index]) {
+          throw new Error("--install-dir requires a path.");
+        }
+        options.installDir = expandHome(argv[index]);
+        break;
+      default:
+        throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function expandHome(value) {
+  if (value === "~") {
+    return os.homedir();
+  }
+  if (value.startsWith("~/")) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+  return path.resolve(value);
+}
+
+function download(url, destination) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, response => {
+      if ([301, 302, 303, 307, 308].includes(response.statusCode)) {
+        response.resume();
+        download(response.headers.location, destination).then(resolve, reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`Download failed with HTTP ${response.statusCode}`));
+        return;
+      }
+
+      const file = fs.createWriteStream(destination);
+      response.pipe(file);
+      file.on("finish", () => file.close(resolve));
+      file.on("error", reject);
+    });
+
+    request.on("error", reject);
+  });
+}
+
+function copyApp(source, destination) {
+  if (fs.existsSync(destination)) {
+    fs.rmSync(destination, { recursive: true, force: true });
+  }
+  run("/usr/bin/ditto", [source, destination]);
+}
+
+function quitRunningApp() {
+  try {
+    run("/usr/bin/osascript", ["-e", `tell application id "${bundleIdentifier}" to quit`], {
+      stdio: "ignore",
+      timeout: 3000
+    });
+  } catch {
+    try {
+      run("/usr/bin/killall", [appName], { stdio: "ignore", timeout: 3000 });
+    } catch {
+      // The app may not be running yet.
+    }
+  }
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    usage();
+    return;
+  }
+  if (options.version) {
+    console.log(packageJson.version);
+    return;
+  }
+
+  if (process.platform !== "darwin") {
+    console.error("Clippa is a macOS app. Run this installer on macOS.");
+    process.exit(1);
+  }
+
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "clippa-install-"));
+  const zipPath = path.join(tempDir, "Clippa.app.zip");
+  const extractDir = path.join(tempDir, "extract");
+
+  try {
+    fs.mkdirSync(extractDir, { recursive: true });
+
+    if (fs.existsSync(localZipPath)) {
+      fs.copyFileSync(localZipPath, zipPath);
+    } else {
+      console.log(`Downloading Clippa from ${zipUrl}`);
+      await download(zipUrl, zipPath);
+    }
+
+    run("/usr/bin/ditto", ["-x", "-k", zipPath, extractDir]);
+
+    const appPath = path.join(extractDir, `${appName}.app`);
+    if (!fs.existsSync(appPath)) {
+      throw new Error(`Archive did not contain ${appName}.app`);
+    }
+
+    quitRunningApp();
+
+    let installDir = options.installDir || "/Applications";
+    let installPath = path.join(installDir, `${appName}.app`);
+    if (options.installDir) {
+      fs.mkdirSync(installDir, { recursive: true });
+      copyApp(appPath, installPath);
+    } else {
+      try {
+        copyApp(appPath, installPath);
+      } catch (error) {
+        installDir = path.join(os.homedir(), "Applications");
+        fs.mkdirSync(installDir, { recursive: true });
+        installPath = path.join(installDir, `${appName}.app`);
+        copyApp(appPath, installPath);
+      }
+    }
+
+    console.log(`Installed ${appName} to ${installPath}`);
+    if (!options.noOpen) {
+      console.log("Opening Clippa...");
+      run("/usr/bin/open", [installPath]);
+      console.log("Press Command-Shift-W in a text field to open Clippa. Grant Accessibility access if macOS asks.");
+    }
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+main().catch(error => {
+  console.error(error.message);
+  process.exit(1);
+});

package/docs/assets/screenshot-panel.svg

@@ -0,0 +1,39 @@
+<svg width="1440" height="900" viewBox="0 0 1440 900" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="1440" height="900" fill="#111414"/>
+  <rect x="340" y="164" width="760" height="520" rx="30" fill="#181C1D"/>
+  <rect x="340.5" y="164.5" width="759" height="519" rx="29.5" stroke="#3A4242"/>
+  <filter id="shadow" x="300" y="124" width="840" height="600" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse">
+    <feDropShadow dx="0" dy="26" stdDeviation="28" flood-color="#000000" flood-opacity=".34"/>
+  </filter>
+  <g filter="url(#shadow)">
+    <rect x="340" y="164" width="760" height="520" rx="30" fill="#181C1D"/>
+    <rect x="340.5" y="164.5" width="759" height="519" rx="29.5" stroke="#3A4242"/>
+  </g>
+  <circle cx="388" cy="221" r="24" fill="#0A84FF"/>
+  <path d="M379 230l29-29a10 10 0 0 1 14 14l-32 32a17 17 0 0 1-24-24l31-31" stroke="#06131F" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="430" y="215" fill="#F4F7F5" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif" font-size="25" font-weight="760">Clippa</text>
+  <text x="430" y="244" fill="#9BA6A2" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif" font-size="16" font-weight="620">4 Items</text>
+  <line x1="380" y1="282" x2="1060" y2="282" stroke="#303838"/>
+  <rect x="380" y="314" width="680" height="72" rx="14" fill="#12365B"/>
+  <rect x="380.5" y="314.5" width="679" height="71" rx="13.5" stroke="#0A84FF" stroke-opacity=".62"/>
+  <rect x="402" y="330" width="42" height="42" rx="10" fill="#20364F"/>
+  <path d="M414 361h20M414 351h25M414 341h18" stroke="#B6C2C9" stroke-width="4" stroke-linecap="round"/>
+  <text x="464" y="346" fill="#F5F8F6" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif" font-size="21" font-weight="720">Release checklist</text>
+  <text x="464" y="371" fill="#B1BEC8" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif" font-size="15" font-weight="610">Text / Notes</text>
+  <rect x="380" y="398" width="680" height="72" rx="14" fill="#202526"/>
+  <rect x="402" y="414" width="42" height="42" rx="10" fill="#143C38"/>
+  <path d="M413 447l14-17 10 12 6-7 13 17h-43v-5z" fill="#64D2C8"/>
+  <text x="464" y="430" fill="#F5F8F6" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif" font-size="21" font-weight="720">Clipboard image</text>
+  <text x="464" y="455" fill="#98A4A0" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif" font-size="15" font-weight="610">1280 x 720 / 482 KB / Preview</text>
+  <rect x="380" y="482" width="680" height="72" rx="14" fill="#202526"/>
+  <rect x="402" y="498" width="42" height="42" rx="10" fill="#223B58"/>
+  <path d="M413 522c7-9 13-9 20 0s13 9 20 0" stroke="#8EC5FF" stroke-width="5" stroke-linecap="round"/>
+  <text x="464" y="514" fill="#F5F8F6" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif" font-size="21" font-weight="720">https://example.com/research</text>
+  <text x="464" y="539" fill="#98A4A0" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif" font-size="15" font-weight="610">URL / Safari</text>
+  <rect x="380" y="566" width="680" height="72" rx="14" fill="#202526"/>
+  <rect x="402" y="582" width="42" height="42" rx="10" fill="#3A3324"/>
+  <path d="M414 595h18l8 8v20h-26v-28z" stroke="#FFD479" stroke-width="4" stroke-linejoin="round"/>
+  <text x="464" y="598" fill="#F5F8F6" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif" font-size="21" font-weight="720">invoice.pdf</text>
+  <text x="464" y="623" fill="#98A4A0" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif" font-size="15" font-weight="610">File / Finder</text>
+  <text x="380" y="724" fill="#75817D" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif" font-size="18" font-weight="650">Command-Shift-W opens Clippa. Enter or click pastes the selected item.</text>
+</svg>

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "clippa",
+  "version": "1.0.0",
+  "description": "Installer for Clippa, a private macOS paste panel.",
+  "bin": {
+    "install-clippa": "bin/install-clippa.js",
+    "clippa": "bin/install-clippa.js",
+    "Clippa": "bin/install-clippa.js"
+  },
+  "scripts": {
+    "release": "./scripts/release.sh",
+    "test": "xcodebuild -project Clippa.xcodeproj -scheme Clippa -destination 'platform=macOS' test"
+  },
+  "files": [
+    "bin",
+    "docs/assets",
+    "outputs/Clippa.app.zip",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vaniawl/Clippa.git"
+  },
+  "homepage": "https://vaniawl.github.io/Clippa/",
+  "bugs": {
+    "url": "https://github.com/Vaniawl/Clippa/issues"
+  },
+  "keywords": [
+    "macos",
+    "clipboard",
+    "swiftui",
+    "productivity"
+  ],
+  "license": "MIT"
+}