lazy-skill 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lazy Skill
+
+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

@@ -1,15 +1,58 @@
-# Lazy Skill
+# lazy-skill
 
 **See it. Search it. Install it.**
 
 Found an AI skill while scrolling? Stop hunting for the repo, the README, and
-the install command buried in step four.
+the install command buried in step four. Search it on Lazy Skill and send it
+straight to your computer — from your phone.
 
-## Not released yet
+## Connect your computer
 
-This version reserves the name. The CLI is built but is not published until
-its service is live, because a released `npx lazy-skill connect` needs a real
-server to pair against — shipping one that points nowhere would just waste
-your time.
+```bash
+npx lazy-skill connect
+```
 
-Watch this space, or check back for `0.1.0`.
+Scan the QR it prints with the Lazy Skill app. That's the whole setup.
+
+```bash
+npx lazy-skill listen      # wait for installs sent from your phone
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `lazy-skill connect` | Pair this computer with the app |
+| `lazy-skill listen` | Wait for installs sent from your phone |
+| `lazy-skill status` | Show the connection and detected tools |
+| `lazy-skill skills` | List skills installed on this computer |
+| `lazy-skill install <ref>` | Install a skill locally |
+| `lazy-skill theme [id]` | Pick a colour theme |
+| `lazy-skill disconnect` | Revoke this computer |
+
+## Supported tools
+
+Claude Code, Codex and Cursor. Detected by looking for them — never assumed.
+Anything not found is reported as "Not detected", never as ready.
+
+## What this does and does not do
+
+Installation runs through [`skills`](https://www.npmjs.com/package/skills), the
+upstream installer, at a pinned version.
+
+**This is not a remote shell.** The server can queue one of four named
+operations with structured parameters; it cannot send a command line, a path,
+or a flag. Everything the server sends is re-validated on your machine before
+anything runs, against a copy of the rules the CLI carries itself — so a
+compromised server still cannot make your computer run something arbitrary.
+
+Your device credential lives in `~/.lazyskill/config.json`, written `0600`.
+Pairing codes are single-use and expire in two minutes.
+
+## Requirements
+
+Node.js 18 or newer.
+
+## Licence
+
+MIT

package/dist/adapters/base.js

@@ -0,0 +1,18 @@
+import { createInstallPlan } from "./install-plan.js";
+import { runInstall } from "./runner.js";
+/**
+ * Every adapter installs the same way — through the one supported pathway —
+ * so the mechanism lives here rather than being copied per agent. What differs
+ * per agent is its identifier and where it reads skills from, and those stay
+ * in the adapter.
+ */
+export function installVia(upstreamId, plan, onProgress) {
+    // Re-narrow the plan to this adapter's own agent. An adapter must never
+    // install to an agent it does not represent, even if handed a wider plan.
+    const scoped = createInstallPlan({
+        skillRef: plan.skillRef,
+        agents: [upstreamId],
+        scope: plan.scope,
+    });
+    return runInstall(scoped, onProgress);
+}

package/dist/adapters/claude.js

@@ -0,0 +1,27 @@
+import { anyExists, homePath, onPath } from "./detect.js";
+import { installVia } from "./base.js";
+/**
+ * Claude. Detected by its config directory or its binary on PATH — never
+ * assumed present (§13).
+ */
+export const claudeAdapter = {
+    id: "claude",
+    label: "Claude",
+    upstreamId: "claude-code",
+    skillsDir() {
+        return homePath(".claude", "skills");
+    },
+    async detect() {
+        const dir = anyExists([
+            homePath(".claude"),
+        ]);
+        if (dir)
+            return { detected: true, evidence: dir };
+        if (await onPath("claude"))
+            return { detected: true, evidence: "claude on PATH" };
+        return { detected: false };
+    },
+    install(plan, onProgress) {
+        return installVia("claude-code", plan, onProgress);
+    },
+};

package/dist/adapters/codex.js

@@ -0,0 +1,27 @@
+import { anyExists, homePath, onPath } from "./detect.js";
+import { installVia } from "./base.js";
+/**
+ * Codex. Detected by its config directory or its binary on PATH — never
+ * assumed present (§13).
+ */
+export const codexAdapter = {
+    id: "codex",
+    label: "Codex",
+    upstreamId: "codex",
+    skillsDir() {
+        return homePath(".codex", "skills");
+    },
+    async detect() {
+        const dir = anyExists([
+            homePath(".codex"),
+        ]);
+        if (dir)
+            return { detected: true, evidence: dir };
+        if (await onPath("codex"))
+            return { detected: true, evidence: "codex on PATH" };
+        return { detected: false };
+    },
+    install(plan, onProgress) {
+        return installVia("codex", plan, onProgress);
+    },
+};

package/dist/adapters/cursor.js

@@ -0,0 +1,30 @@
+import { anyExists, homePath, onPath } from "./detect.js";
+import { installVia } from "./base.js";
+/**
+ * Cursor. Detected by its config directory or its binary on PATH — never
+ * assumed present (§13).
+ */
+export const cursorAdapter = {
+    id: "cursor",
+    label: "Cursor",
+    upstreamId: "cursor",
+    skillsDir() {
+        return homePath(".cursor", "skills");
+    },
+    async detect() {
+        const dir = anyExists([
+            homePath(".cursor"),
+            "/Applications/Cursor.app",
+            homePath("Applications", "Cursor.app"),
+            homePath("AppData", "Local", "Programs", "cursor"),
+        ]);
+        if (dir)
+            return { detected: true, evidence: dir };
+        if (await onPath("cursor"))
+            return { detected: true, evidence: "cursor on PATH" };
+        return { detected: false };
+    },
+    install(plan, onProgress) {
+        return installVia("cursor", plan, onProgress);
+    },
+};

package/dist/adapters/detect.js

@@ -0,0 +1,34 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+/** True when `name` resolves on PATH. */
+export async function onPath(name) {
+    // A fixed lookup tool with the name passed as an argument — never a shell
+    // string, so a crafted name cannot become a command.
+    const finder = process.platform === "win32" ? "where" : "which";
+    try {
+        const { stdout } = await run(finder, [name], { timeout: 3000 });
+        return stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function homePath(...segments) {
+    return join(homedir(), ...segments);
+}
+export function anyExists(paths) {
+    for (const path of paths) {
+        try {
+            if (existsSync(path))
+                return path;
+        }
+        catch {
+            // Unreadable path is not a detection.
+        }
+    }
+    return null;
+}

package/dist/adapters/index.js

@@ -0,0 +1,25 @@
+import { claudeAdapter } from "./claude.js";
+import { codexAdapter } from "./codex.js";
+import { cursorAdapter } from "./cursor.js";
+export { createInstallPlan, describePlan, isValidSkillRef, InvalidPlanError, UPSTREAM_AGENTS, } from "./install-plan.js";
+export const ADAPTERS = [claudeAdapter, codexAdapter, cursorAdapter];
+export function adapterFor(id) {
+    return ADAPTERS.find((adapter) => adapter.id === id) ?? null;
+}
+/** Runs every detector in parallel. A detector that throws counts as absent. */
+export async function detectAgents() {
+    return Promise.all(ADAPTERS.map(async (adapter) => {
+        try {
+            const result = await adapter.detect();
+            return {
+                id: adapter.id,
+                label: adapter.label,
+                detected: result.detected,
+                evidence: result.evidence,
+            };
+        }
+        catch {
+            return { id: adapter.id, label: adapter.label, detected: false };
+        }
+    }));
+}

package/dist/adapters/install-plan.js

@@ -0,0 +1,105 @@
+/**
+ * Turning a request into a command, safely.
+ *
+ * This module is the entire trust boundary for installation. A skill
+ * reference may originate from a phone, a server, or a shell argument, so it
+ * is validated against a strict pattern here and only ever emitted as a
+ * distinct element of an argv array — never interpolated into a string.
+ *
+ * Nothing in this file executes anything. Building a plan and running one are
+ * deliberately separate, so the dangerous part stays pure and testable.
+ */
+/** Agents the upstream installer accepts. Verified against skills@1.5.23. */
+export const UPSTREAM_AGENTS = [
+    "claude-code",
+    "codex",
+    "cursor",
+    "copilot",
+    "windsurf",
+    "gemini",
+];
+/**
+ * The installer this CLI delegates to, pinned.
+ *
+ * Deliberately not a floating tag: an unpinned `npx` fetches and executes
+ * whatever the registry serves at that moment. Bump this on purpose, after
+ * looking at what changed.
+ */
+export const UPSTREAM_PACKAGE = "skills@1.5.23";
+/**
+ * A skill reference: `owner/repo`, optionally `owner/repo/skill`.
+ *
+ * Anchored, no dots, no leading dashes. That last part matters most: a
+ * reference beginning with `-` would be read by the installer as a flag
+ * rather than a package.
+ */
+const REF_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_-]*(?:\/[A-Za-z0-9_][A-Za-z0-9_.-]*){1,2}$/;
+const MAX_REF_LENGTH = 200;
+export class InvalidPlanError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidPlanError";
+    }
+}
+export function isValidSkillRef(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= MAX_REF_LENGTH &&
+        REF_PATTERN.test(value) &&
+        // Path traversal would escape the skills directory entirely.
+        !value.includes(".."));
+}
+export function isUpstreamAgent(value) {
+    return typeof value === "string" && UPSTREAM_AGENTS.includes(value);
+}
+/**
+ * Validates a request into a plan. Throws rather than sanitising: a reference
+ * we had to repair is a reference we do not understand, and quietly installing
+ * something adjacent to what was asked for is worse than refusing.
+ */
+export function createInstallPlan(input) {
+    if (!isValidSkillRef(input.skillRef)) {
+        throw new InvalidPlanError("That skill reference is not valid. Expected something like owner/repo.");
+    }
+    if (!Array.isArray(input.agents) || input.agents.length === 0) {
+        throw new InvalidPlanError("No target agent was given.");
+    }
+    const agents = [];
+    for (const agent of input.agents) {
+        if (!isUpstreamAgent(agent)) {
+            throw new InvalidPlanError(`Unknown agent "${String(agent)}".`);
+        }
+        if (!agents.includes(agent))
+            agents.push(agent);
+    }
+    const scope = input.scope === "project" ? "project" : "global";
+    return { skillRef: input.skillRef, agents, scope };
+}
+/**
+ * The exact argv passed to the installer.
+ *
+ * Every element is either a fixed literal or a value already validated above,
+ * and the runner spawns with `shell: false`, so no element is ever parsed by a
+ * shell. `--` terminates option parsing so the reference cannot be read as a
+ * flag even if the pattern above is ever loosened.
+ */
+export function buildInstallArgs(plan) {
+    const args = [
+        "--yes",
+        UPSTREAM_PACKAGE,
+        "add",
+        "--agent",
+        plan.agents.join(","),
+        "--skill",
+        "*",
+        "--yes",
+    ];
+    if (plan.scope === "global")
+        args.push("--global");
+    args.push("--", plan.skillRef);
+    return args;
+}
+/** What the user is shown before anything runs (§23). */
+export function describePlan(plan) {
+    return `npx ${buildInstallArgs(plan).join(" ")}`;
+}

package/dist/adapters/runner.js

@@ -0,0 +1,139 @@
+import { spawn } from "node:child_process";
+import { buildInstallArgs, describePlan } from "./install-plan.js";
+/** Upstream prints spinners and colour; neither belongs in our progress. */
+// eslint-disable-next-line no-control-regex
+const CONTROL = /\x1b\[[0-9;?]*[A-Za-z]|\x1b\][^\x07]*\x07|[\r\x00-\x08\x0b\x0c\x0e-\x1f]/g;
+function clean(chunk) {
+    return chunk
+        .replace(CONTROL, "")
+        .split("\n")
+        .map((line) => line.replace(/^[│◇◆●○◒◐◓◑✓✔✗✘|\s]+/, "").trim())
+        .filter((line) => line.length > 0);
+}
+/**
+ * Maps observed output to a stage, matched against the installer's real
+ * markers rather than loose keywords.
+ *
+ * The specificity matters: the very first line upstream prints is
+ * "Agent detected — installing non-interactively", which a bare "installing"
+ * test reads as the install stage before anything has been downloaded.
+ *
+ * Deliberately conservative — an unrecognised line advances nothing rather
+ * than inventing progress the installer never reported (§18).
+ */
+export function stageFor(line) {
+    const text = line.toLowerCase();
+    // The startup banner is not a stage.
+    if (text.includes("non-interactively"))
+        return null;
+    if (text.includes("source:") || text.includes("fetching") || text.includes("cloning")) {
+        return "downloading";
+    }
+    if (/installing (all |\d)/.test(text) || text.includes("copy →") || text.includes("link →")) {
+        return "installing";
+    }
+    if (text.includes("installation summary") ||
+        text.includes("installed") ||
+        text.includes("added")) {
+        return "verifying";
+    }
+    return null;
+}
+/** Stage ordering, used to keep reported progress monotonic. */
+const STAGE_RANK = {
+    starting: 0,
+    downloading: 1,
+    installing: 2,
+    verifying: 3,
+    done: 4,
+    failed: 5,
+};
+export const INSTALL_TIMEOUT_MS = 5 * 60 * 1000;
+export async function runInstall(plan, onProgress, options = {}) {
+    const args = buildInstallArgs(plan);
+    const output = [];
+    onProgress({ stage: "starting", detail: describePlan(plan) });
+    return new Promise((resolve) => {
+        const child = spawn("npx", args, {
+            // No shell. The single most important line in this file.
+            shell: false,
+            cwd: options.cwd ?? process.cwd(),
+            stdio: ["ignore", "pipe", "pipe"],
+            env: {
+                ...process.env,
+                // Keep the child non-interactive and machine-readable. FORCE_COLOR is
+                // removed rather than overridden: it wins over NO_COLOR downstream, so
+                // inheriting a developer's FORCE_COLOR would put escape sequences back
+                // into the output this parser reads.
+                FORCE_COLOR: undefined,
+                CI: "1",
+                NO_COLOR: "1",
+                npm_config_yes: "true",
+            },
+        });
+        let settled = false;
+        let lastStage = "starting";
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill("SIGTERM");
+            // A wedged installer must not hold the device forever.
+            setTimeout(() => child.kill("SIGKILL"), 5000).unref();
+            onProgress({ stage: "failed", detail: "Timed out." });
+            resolve({
+                ok: false,
+                exitCode: null,
+                output,
+                error: "The installer took too long and was stopped.",
+            });
+        }, options.timeoutMs ?? INSTALL_TIMEOUT_MS);
+        const consume = (chunk) => {
+            for (const line of clean(chunk.toString())) {
+                // Bounded: a chatty installer must not grow memory without limit.
+                output.push(line);
+                if (output.length > 200)
+                    output.shift();
+                // Only ever move forward. The installer interleaves its own phases
+                // (it prints an "installing" banner before it starts fetching), and a
+                // progress bar that slides backwards reads as a fault.
+                const next = stageFor(line);
+                if (next && STAGE_RANK[next] > STAGE_RANK[lastStage]) {
+                    lastStage = next;
+                    onProgress({ stage: next, detail: line });
+                }
+            }
+        };
+        child.stdout?.on("data", consume);
+        child.stderr?.on("data", consume);
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            onProgress({ stage: "failed", detail: err.message });
+            resolve({
+                ok: false,
+                exitCode: null,
+                output,
+                error: err.code === "ENOENT"
+                    ? "npx was not found on this computer. Node.js is required."
+                    : err.message,
+            });
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const ok = code === 0;
+            onProgress({ stage: ok ? "done" : "failed" });
+            resolve({
+                ok,
+                exitCode: code,
+                output,
+                error: ok ? undefined : output.at(-1) ?? `Installer exited with code ${code}.`,
+            });
+        });
+    });
+}

package/dist/adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/commands/connect.js

@@ -0,0 +1,149 @@
+import { hostname, platform, release } from "node:os";
+import { api, ApiError } from "../lib/api.js";
+import { readConfig, updateConfig } from "../lib/config.js";
+import { detectAgents } from "../adapters/index.js";
+import { THEMES, rgb, style } from "../ui/theme.js";
+import { bottom, centered, mascot, row, statusLine, top, wordmark } from "../ui/box.js";
+import { renderQr } from "../ui/qr.js";
+import { messages } from "../ui/messages.js";
+import { Spinner } from "../ui/spinner.js";
+function friendlyPlatform() {
+    const p = platform();
+    return p === "darwin" || p === "win32" || p === "linux" ? p : "unknown";
+}
+function deviceName() {
+    return hostname().replace(/\.local$/, "").slice(0, 80) || "This computer";
+}
+function printHeader(theme) {
+    console.log();
+    console.log(top(theme));
+    console.log(row(theme));
+    for (const line of wordmark(theme))
+        console.log(centered(theme, line));
+    console.log(centered(theme, style.dim("Too lazy to install manually? Same.")));
+    console.log(row(theme));
+}
+function printAgents(theme, agents) {
+    console.log(row(theme, style.bold("Detected AI tools")));
+    console.log(row(theme));
+    for (const agent of agents) {
+        console.log(row(theme, statusLine(agent.label, agent.detected ? true : null)));
+    }
+}
+export async function connectCommand(options) {
+    const config = readConfig();
+    const theme = THEMES[config.theme];
+    // Detection runs before the card is drawn. A spinner writes to the current
+    // line, so anything transient printed between two card rows tears the frame.
+    const detectSpinner = new Spinner(theme, messages.booting()[0]).start();
+    const agents = await detectAgents();
+    const detectedIds = agents.filter((a) => a.detected).map((a) => a.id);
+    detectSpinner.stop();
+    printHeader(theme);
+    console.log(row(theme, `${style.gray(">")} ${messages.humanFound()} ${style.green("✓")}`));
+    console.log(row(theme, `${style.gray(">")} ${messages.generating()}`));
+    console.log(row(theme));
+    if (options.verbose) {
+        for (const agent of agents) {
+            if (agent.evidence)
+                console.log(row(theme, style.gray(`  ${agent.label}: ${agent.evidence}`)));
+        }
+        console.log(row(theme));
+    }
+    // --- open a pairing session -----------------------------------------
+    let session;
+    try {
+        session = await api("/api/pairing/start", {
+            body: {
+                deviceName: deviceName(),
+                platform: friendlyPlatform(),
+                osVersion: release(),
+                detectedAgents: detectedIds,
+                theme: theme.id,
+            },
+        });
+    }
+    catch (err) {
+        console.log(bottom(theme));
+        console.log();
+        const message = err instanceof ApiError ? err.message : messages.failed();
+        console.error(`  ${style.red("✗")} ${message}`);
+        console.error(`  ${style.gray("Set LAZY_SKILL_API_URL if you are pointing at a local server.")}`);
+        console.log();
+        return 1;
+    }
+    console.log(bottom(theme));
+    console.log();
+    const qrLines = await renderQr(session.pairUrl);
+    for (const line of qrLines)
+        console.log(line);
+    console.log(`  ${style.bold("Scan with the Lazy Skill app")}`);
+    console.log(`  ${style.gray(session.pairUrl)}`);
+    console.log();
+    // --- wait for the phone ---------------------------------------------
+    const deadline = Date.now() + session.expiresInMs;
+    const waitSpinner = new Spinner(theme, messages.waiting()).start();
+    let lastNudge = Date.now();
+    let result = { status: "waiting" };
+    while (Date.now() < deadline) {
+        await sleep(1500);
+        try {
+            result = await api("/api/pairing/poll", { body: { code: session.code } });
+        }
+        catch {
+            // A dropped poll is not a failed pairing; keep trying until the code
+            // actually expires.
+            continue;
+        }
+        if (result.status !== "waiting")
+            break;
+        // Rotate the waiting line occasionally so a long wait stays alive.
+        if (Date.now() - lastNudge > 12_000) {
+            waitSpinner.update(messages.waiting());
+            lastNudge = Date.now();
+        }
+    }
+    waitSpinner.stop();
+    if (result.status === "paired" && result.deviceToken) {
+        updateConfig({
+            deviceToken: result.deviceToken,
+            deviceId: result.device?.id,
+            deviceName: result.device?.name ?? deviceName(),
+            connectedAt: new Date().toISOString(),
+        });
+        console.log(`  ${style.gray(">")} ${messages.scanned()} ${rgb(theme.support, "📱")}`);
+        console.log(`  ${style.gray(">")} ${messages.authenticating()} ${style.green("✓")}`);
+        console.log();
+        console.log(top(theme));
+        console.log(row(theme));
+        for (const line of mascot(theme, true))
+            console.log(centered(theme, line));
+        console.log(row(theme));
+        console.log(centered(theme, rgb(theme.accent, style.bold(messages.connected()))));
+        console.log(row(theme));
+        printAgents(theme, agents);
+        console.log(row(theme));
+        console.log(centered(theme, style.dim(messages.signOff())));
+        console.log(row(theme));
+        console.log(bottom(theme));
+        console.log();
+        console.log(`  ${style.gray("Credential stored in ~/.lazyskill/config.json (0600).")}`);
+        if (options.listen) {
+            const { listenCommand } = await import("./listen.js");
+            return listenCommand();
+        }
+        console.log(`  ${style.gray("Run")} ${rgb(theme.accent, "lazy-skill listen")} ${style.gray("to install from your phone.")}`);
+        console.log();
+        return 0;
+    }
+    const reason = result.status === "consumed"
+        ? "That code was already used."
+        : messages.expired();
+    console.log(`  ${style.yellow("!")} ${reason}`);
+    console.log(`  ${style.gray("Run")} ${rgb(theme.accent, "npx lazy-skill connect")} ${style.gray("for a fresh one.")}`);
+    console.log();
+    return 1;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}