@seojin08/skill-finder 0.0.0-stage → 0.3.2

package/server/src/util/limiter.js

@@ -0,0 +1,110 @@
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Thrown by `take({ maxWaitMs })` when the queue would make the caller wait longer than that. */
+export class RateLimitWait extends Error {
+}
+/** Token bucket refilled continuously; `take()` waits until a token is available. */
+export class TokenBucket {
+    tokens;
+    last = Date.now();
+    capacity;
+    perMs;
+    queue = Promise.resolve();
+    /** Callers queued and not yet served (each will take one token). */
+    waiting = 0;
+    /**
+     * `capacity` bounds a burst: a full bucket of `perMinute` plus a minute of refill let 18 calls through in
+     * 60s against GitHub's 10/min code-search limit, so the tail got 403s.
+     */
+    constructor(perMinute, capacity = perMinute) {
+        this.capacity = capacity;
+        this.tokens = capacity;
+        this.perMs = perMinute / 60_000;
+    }
+    refill() {
+        const t = Date.now();
+        this.tokens = Math.min(this.capacity, this.tokens + (t - this.last) * this.perMs);
+        this.last = t;
+    }
+    /** Milliseconds until a token would be available (0 = now). */
+    waitTime() {
+        this.refill();
+        return this.tokens >= 1 ? 0 : Math.ceil((1 - this.tokens) / this.perMs);
+    }
+    /**
+     * `maxWaitMs`: give up at once (RateLimitWait) when the token would come later than that, instead of
+     * queuing. A caller that stops waiting on its own (a search past its deadline) otherwise still takes a
+     * token later and starves the next search.
+     */
+    take(opts = {}) {
+        if (opts.maxWaitMs != null) {
+            // tokens this caller needs on top of those already in the bucket (the queue goes first)
+            this.refill();
+            const deficit = this.waiting + 1 - this.tokens;
+            const ahead = deficit <= 0 ? 0 : deficit / this.perMs;
+            if (ahead > opts.maxWaitMs)
+                return Promise.reject(new RateLimitWait(`대기 ${Math.ceil(ahead / 1000)}초 예상`));
+        }
+        this.waiting++;
+        const next = this.queue.then(async () => {
+            let wait = this.waitTime();
+            while (wait > 0) {
+                await sleep(wait);
+                wait = this.waitTime();
+            }
+            this.tokens -= 1;
+            this.waiting--;
+        });
+        this.queue = next.catch(() => { });
+        return next;
+    }
+}
+/** At most `limit` holders at once across all callers (e.g. raw GitHub downloads from many lookups). */
+export class Semaphore {
+    active = 0;
+    waiting = [];
+    limit;
+    constructor(limit) {
+        this.limit = limit;
+    }
+    async run(fn) {
+        if (this.active >= this.limit)
+            await new Promise((resolve) => this.waiting.push(resolve));
+        this.active++;
+        try {
+            return await fn();
+        }
+        finally {
+            this.active--;
+            this.waiting.shift()?.();
+        }
+    }
+}
+/** Runs `fn` over items with bounded concurrency; results keep input order. Errors are returned, not thrown. */
+export async function pool(items, concurrency, fn, shouldStop) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            if (shouldStop?.())
+                return;
+            const i = next++;
+            try {
+                results[i] = { ok: true, value: await fn(items[i], i) };
+            }
+            catch (error) {
+                results[i] = { ok: false, error };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+    return results;
+}
+export function withTimeout(p, ms, label = 'timeout') {
+    let timer;
+    return Promise.race([
+        p.finally(() => clearTimeout(timer)),
+        new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(label)), ms);
+        }),
+    ]);
+}

package/server/src/util/log.js

@@ -0,0 +1,94 @@
+// A log file next to the index (project review F2): what the console shows, with secrets masked, so a problem can
+// be looked at after the window is closed. Kept on this PC only; rotated at 1MB, three old files kept.
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { format } from 'node:util';
+const MAX_BYTES = 1024 * 1024;
+const KEEP = 3;
+let file = null;
+let extraSecrets = [];
+let patched = false;
+/** GitHub tokens of every kind, bearer headers, and values of known secret names; the home folder becomes `~`. */
+export function maskSecrets(text) {
+    let out = text
+        .replace(/\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})/g, '[가림]')
+        .replace(/\b(Bearer|token)\s+[A-Za-z0-9._~+/=-]{12,}/gi, '$1 [가림]')
+        .replace(/\b(GITHUB_TOKEN|DATABASE_URL|API_KEY|SECRET)\s*[=:]\s*\S+/gi, '$1=[가림]');
+    for (const s of extraSecrets)
+        if (s)
+            out = out.split(s).join('[가림]');
+    const home = homedir();
+    return home ? out.split(home).join('~') : out;
+}
+function rotate(path) {
+    try {
+        if (!existsSync(path) || statSync(path).size < MAX_BYTES)
+            return;
+        rmSync(`${path}.${KEEP}`, { force: true });
+        for (let i = KEEP - 1; i >= 1; i--)
+            if (existsSync(`${path}.${i}`))
+                renameSync(`${path}.${i}`, `${path}.${i + 1}`);
+        renameSync(path, `${path}.1`);
+    }
+    catch {
+        // another process holds the file, or it vanished: keep writing to it
+    }
+}
+function write(level, args) {
+    if (!file)
+        return;
+    try {
+        rotate(file);
+        appendFileSync(file, `${new Date().toISOString()} ${level} ${maskSecrets(format(...args))}\n`);
+    }
+    catch {
+        // a full disk or a locked file must never stop the app
+    }
+}
+/**
+ * Copies console.log/warn/error into `<dataDir>/logs/server.log`. `secrets`: values to mask besides the token
+ * patterns (the configured GitHub token). The console itself still shows everything as before.
+ */
+export function startLogFile(dataDir, secrets = []) {
+    const dir = join(dataDir, 'logs');
+    mkdirSync(dir, { recursive: true });
+    file = join(dir, 'server.log');
+    extraSecrets = secrets.filter((s) => !!s && s.length >= 8);
+    // a second call (tests) only moves the file; the console is wrapped once
+    if (patched)
+        return file;
+    patched = true;
+    for (const [name, level] of [
+        ['log', 'INFO'],
+        ['warn', 'WARN'],
+        ['error', 'ERROR'],
+    ]) {
+        const original = console[name].bind(console);
+        console[name] = (...args) => {
+            original(...args);
+            write(level, args);
+        };
+    }
+    return file;
+}
+/** A newly set token is masked from then on. */
+export function addSecret(value) {
+    if (value && value.length >= 8 && !extraSecrets.includes(value))
+        extraSecrets.push(value);
+}
+/** The last `lines` lines of the current log file (already masked when written). */
+export function logTail(lines) {
+    if (!file || !existsSync(file))
+        return '';
+    try {
+        const text = readFileSync(file, 'utf8');
+        return text.split('\n').slice(-lines - 1).join('\n').trim();
+    }
+    catch {
+        return '';
+    }
+}
+export function logFilePath() {
+    return file;
+}

package/server/src/util/ndjson.js

@@ -0,0 +1,27 @@
+export function ndjson(res) {
+    res.status(200);
+    res.setHeader('Content-Type', 'application/x-ndjson; charset=utf-8');
+    res.setHeader('Cache-Control', 'no-store');
+    res.setHeader('X-Accel-Buffering', 'no');
+    res.flushHeaders();
+    let closed = false;
+    res.on('close', () => {
+        closed = true;
+    });
+    return {
+        send(event) {
+            if (closed)
+                return;
+            res.write(JSON.stringify(event) + '\n');
+        },
+        end() {
+            if (closed)
+                return;
+            closed = true;
+            res.end();
+        },
+        get closed() {
+            return closed;
+        },
+    };
+}

package/server/src/util/proc.js

@@ -0,0 +1,80 @@
+import { spawn } from 'node:child_process';
+import { sanitizeText } from "./sanitize.js";
+/** Runs a process without a shell (unless explicitly requested), collecting sanitized output. */
+export function run(file, args, opts = {}) {
+    const hook = globalThis.__skillFinderProcHook;
+    return hook ? hook(file, args, opts, spawnRun) : spawnRun(file, args, opts);
+}
+/**
+ * Ends a process and the ones it started (node → skills CLI → git). On Windows child.kill() ends only the first,
+ * which left git clones running after a timeout (project review F2).
+ */
+export function killTree(child) {
+    if (process.platform === 'win32' && child.pid) {
+        const k = spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
+        k.on('error', () => child.kill());
+    }
+    else {
+        child.kill();
+    }
+}
+function spawnRun(file, args, opts) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(file, args, {
+            cwd: opts.cwd,
+            env: opts.env ?? process.env,
+            shell: opts.shell ?? false,
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        const partial = { stdout: '', stderr: '' };
+        const timer = opts.timeoutMs
+            ? setTimeout(() => {
+                timedOut = true;
+                killTree(child);
+            }, opts.timeoutMs)
+            : null;
+        // decoded per stream, not per chunk: a multi-byte character (a Korean folder name in `git ls-tree`) split
+        // across two chunks would otherwise turn into replacement characters
+        const onData = (stream) => (text) => {
+            if (stream === 'stdout')
+                stdout += text;
+            else
+                stderr += text;
+            if (!opts.onLine)
+                return;
+            const lines = (partial[stream] + text).split(/\r?\n/);
+            partial[stream] = lines.pop() ?? '';
+            for (const line of lines) {
+                const clean = sanitizeText(line).trimEnd();
+                if (clean)
+                    opts.onLine(clean, stream);
+            }
+        };
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', onData('stdout'));
+        child.stderr.on('data', onData('stderr'));
+        child.on('error', (err) => {
+            if (timer)
+                clearTimeout(timer);
+            reject(err);
+        });
+        child.on('close', (code) => {
+            if (timer)
+                clearTimeout(timer);
+            if (opts.onLine) {
+                for (const stream of ['stdout', 'stderr']) {
+                    const clean = sanitizeText(partial[stream]).trimEnd();
+                    if (clean)
+                        opts.onLine(clean, stream);
+                }
+            }
+            const clean = opts.raw ? (s) => s : sanitizeText;
+            resolve({ exitCode: code ?? -1, stdout: clean(stdout), stderr: clean(stderr), timedOut });
+        });
+    });
+}

package/server/src/util/resolveFolder.js

@@ -0,0 +1,78 @@
+import { readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+/**
+ * Drag & drop of a folder into the browser gives its name and the names inside it, never its absolute
+ * path (browser security). This finds the folder on disk: a breadth-first walk from the user's home
+ * (plus a few given hint folders) for directories with that name, ranked by how many of the dropped
+ * entries they contain. Only directory listings are read.
+ */
+const SKIP = new Set(['node_modules', 'appdata', 'library', '$recycle.bin', 'windows', 'program files', 'program files (x86)', 'dist', 'build', 'target', 'venv', '__pycache__']);
+const MAX_DEPTH = 6;
+const MAX_DIRS = 40_000;
+const TIME_LIMIT_MS = 3000;
+/** A candidate must contain at least this share of the dropped entries. */
+const MIN_OVERLAP = 0.6;
+const sameName = (a, b) => (process.platform === 'win32' || process.platform === 'darwin' ? a.toLowerCase() === b.toLowerCase() : a === b);
+function listNames(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveDroppedFolder(name, entries, hints = []) {
+    const wanted = new Set(entries.map((e) => e.toLowerCase()));
+    const started = Date.now();
+    const seen = new Set();
+    const matches = [];
+    const queue = [];
+    const home = homedir();
+    // Hints first (parents of known project folders), then the whole home tree.
+    for (const h of [...hints.map((p) => dirname(p)), home])
+        if (h)
+            queue.push([h, 0]);
+    let visited = 0;
+    while (queue.length && visited < MAX_DIRS && Date.now() - started < TIME_LIMIT_MS) {
+        const [dir, depth] = queue.shift();
+        const key = dir.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        visited++;
+        const children = listNames(dir);
+        if (!children)
+            continue;
+        for (const c of children) {
+            if (!c.isDirectory())
+                continue;
+            const lower = c.name.toLowerCase();
+            const full = join(dir, c.name);
+            if (sameName(c.name, name)) {
+                const inside = listNames(full);
+                if (inside) {
+                    const names = new Set(inside.map((e) => e.name.toLowerCase()));
+                    const hit = wanted.size ? [...wanted].filter((w) => names.has(w)).length / wanted.size : 1;
+                    if (hit >= MIN_OVERLAP && !matches.some((m) => m.path.toLowerCase() === full.toLowerCase()))
+                        matches.push({ path: full, overlap: hit });
+                }
+            }
+            if (depth + 1 < MAX_DEPTH && !lower.startsWith('.') && !SKIP.has(lower))
+                queue.push([full, depth + 1]);
+        }
+    }
+    const mtime = (p) => {
+        try {
+            return statSync(p).mtimeMs;
+        }
+        catch {
+            return 0;
+        }
+    };
+    return matches.sort((a, b) => b.overlap - a.overlap || mtime(b.path) - mtime(a.path)).slice(0, 5);
+}
+/** Folder name check for the API: one path segment, no traversal. */
+export function isPlainFolderName(name) {
+    return name.length > 0 && name.length <= 255 && name === basename(name) && name !== '.' && name !== '..' && !/[\\/\0]/.test(name);
+}

package/server/src/util/sanitize.js

@@ -0,0 +1,45 @@
+// Same escape classes the skills CLI strips (src/cli: stripTerminalEscapes).
+const CSI_RE = /\x1b\[[\x30-\x3f]*[\x20-\x2f]*[\x40-\x7e]/g;
+// OSC/DCS bodies stop at the next ESC (or BEL): a lazy `[\s\S]*?` scanned to the end of the text from every
+// unterminated ESC], quadratic (95s on a crafted 512KB SKILL.md). A sequence with an ESC inside is no longer
+// removed whole, but its ESCs are still stripped below, so no escape survives either way.
+const OSC_RE = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+const DCS_PM_APC_RE = /\x1b[P^_][^\x1b]*\x1b\\/g;
+const SIMPLE_ESC_RE = /\x1b[\x20-\x7e]/g;
+const C1_RE = /[\x80-\x9f]/g;
+// Keeps \t (0x09) and \n (0x0a); drops other C0 controls, \r and DEL.
+const CONTROL_RE = /[\x00-\x08\x0b-\x1f\x7f]/g;
+/** Removes ANSI/terminal escape sequences and control characters, keeping newlines and tabs. */
+export function sanitizeText(input) {
+    return input
+        .replace(/\r\n?/g, '\n')
+        .replace(OSC_RE, '')
+        .replace(DCS_PM_APC_RE, '')
+        .replace(CSI_RE, '')
+        .replace(SIMPLE_ESC_RE, '')
+        .replace(C1_RE, '')
+        .replace(CONTROL_RE, '');
+}
+// Direction overrides/isolates and marks, zero-width space, word joiner, BOM: invisible, and able to make a
+// name read as something else ("txt.exe" shown as "exe.txt").
+const INVISIBLE_RE = /[؜​‎‏‪-‮⁠⁦-⁩]/g;
+// Zero-width (non-)joiners shape Persian, Indic scripts and emoji, so descriptions keep them; names do not.
+const JOINER_RE = /[‌‍]/g;
+/** sanitizeText plus newline collapsing, for single-line metadata. */
+export function sanitizeLine(input) {
+    // split + trim rather than /\s*\n\s*/: that regex rescans a long whitespace run from every position (2.9s at 64K)
+    return sanitizeText(input)
+        .replace(INVISIBLE_RE, '')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .join(' ');
+}
+/** sanitizeLine for names, also without zero-width joiners. */
+export function sanitizeName(input) {
+    return sanitizeLine(input).replace(JOINER_RE, '');
+}
+export function truncate(input, max) {
+    const chars = Array.from(input);
+    return chars.length <= max ? input : chars.slice(0, max - 1).join('') + '…';
+}

package/server/src/util/sizedCache.js

@@ -0,0 +1,74 @@
+/**
+ * A cache of promises bounded by the total size of what they hold (tree entries), not by their count: one giant
+ * repo tree weighs as much as hundreds of small ones, and a count cap let a popular-repo collection keep 157MB of
+ * trees until the app quit (perf debate 1-3). The least recently used entry goes first and every entry expires
+ * after `ttlMs`. A rejected promise is dropped. The newest entry stays even when it alone is over the limit,
+ * until the next one arrives.
+ */
+export class SizedCache {
+    entries = new Map();
+    maxSize;
+    ttlMs;
+    sizeOf;
+    now;
+    total = 0;
+    constructor(opts) {
+        this.maxSize = opts.maxSize;
+        this.ttlMs = opts.ttlMs;
+        this.sizeOf = opts.sizeOf;
+        this.now = opts.now ?? Date.now;
+    }
+    get(key) {
+        const e = this.entries.get(key);
+        if (!e)
+            return undefined;
+        if (this.now() - e.at > this.ttlMs) {
+            this.remove(key);
+            return undefined;
+        }
+        // most recently used last
+        this.entries.delete(key);
+        this.entries.set(key, e);
+        return e.value;
+    }
+    set(key, value) {
+        this.remove(key);
+        const e = { value, size: 0, at: this.now() };
+        this.entries.set(key, e);
+        value.then((v) => {
+            if (this.entries.get(key) !== e)
+                return; // replaced or dropped meanwhile
+            e.size = this.sizeOf(v);
+            this.total += e.size;
+            this.evict(key);
+        }, () => {
+            if (this.entries.get(key) === e)
+                this.entries.delete(key);
+        });
+    }
+    /** Entries held and their total size (for tests and diagnostics). */
+    stats() {
+        return { count: this.entries.size, size: this.total };
+    }
+    remove(key) {
+        const e = this.entries.get(key);
+        if (!e)
+            return;
+        this.total -= e.size;
+        this.entries.delete(key);
+    }
+    evict(keep) {
+        const now = this.now();
+        for (const [k, e] of this.entries) {
+            if (k !== keep && now - e.at > this.ttlMs)
+                this.remove(k);
+        }
+        for (const [k, e] of this.entries) {
+            if (this.total <= this.maxSize)
+                break;
+            // a pending entry weighs nothing yet: dropping it would free nothing
+            if (k !== keep && e.size > 0)
+                this.remove(k);
+        }
+    }
+}

package/server/src/util/textFiles.js

@@ -0,0 +1,9 @@
+// Which skill files are text: opened in the 파일 tab and checked before an install.
+/** The most read of one file (the 파일 tab and the install scan). */
+export const MAX_FILE_BYTES = 256 * 1024;
+const TEXT_EXT = /\.(md|markdown|mdx|txt|rst|json|jsonc|ya?ml|toml|ini|cfg|conf|env|py|js|mjs|cjs|ts|tsx|jsx|sh|bash|zsh|fish|ps1|psm1|bat|cmd|rb|pl|php|lua|r|go|rs|java|kt|swift|c|h|cc|cpp|hpp|cs|scala|sql|html?|css|scss|xml|svg|csv|tsv|graphql|proto|tf|hcl|gradle|properties|lock|gitignore|dockerignore|editorconfig)$/i;
+const TEXT_NAMES = /^(LICENSE|LICENCE|NOTICE|README|CHANGELOG|Makefile|Dockerfile|Gemfile|Procfile|\.[a-z]+rc)(\.[a-z]+)?$/i;
+export function isTextPath(path) {
+    const name = path.split('/').pop() ?? path;
+    return TEXT_EXT.test(name) || TEXT_NAMES.test(name);
+}

package/server/src/util/tokens.js

@@ -0,0 +1,21 @@
+// How much of the model's context a skill takes (review 2026-11-02: Claude Code shows this for the official
+// marketplace only). Counted without a tokenizer or any AI call, so it is an estimate and is shown as one.
+/** About 4 characters per token for ASCII text, 1.5 per character for other scripts (Korean, CJK). */
+export function estimateTokens(text) {
+    let ascii = 0;
+    let other = 0;
+    for (const ch of text) {
+        if (ch.charCodeAt(0) < 128)
+            ascii++;
+        else
+            other++;
+    }
+    return Math.ceil(ascii / 4 + other / 1.5);
+}
+/**
+ * `perTurn`: the name and description Claude Code lists with every request while the skill is installed;
+ * `onUse`: the whole SKILL.md, read when the skill is used (null when not known).
+ */
+export function skillTokens(name, description, skillMd) {
+    return { perTurn: estimateTokens(`${name}: ${description ?? ''}`), onUse: skillMd == null ? null : estimateTokens(skillMd) };
+}

package/server/src/version.js

@@ -0,0 +1,12 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ROOT_DIR } from "./config.js";
+/** The app's version from the root package.json (the release zip writes its own with the same version). */
+export const APP_VERSION = (() => {
+    try {
+        return String(JSON.parse(readFileSync(join(ROOT_DIR, 'package.json'), 'utf8')).version ?? '') || null;
+    }
+    catch {
+        return null;
+    }
+})();

package/web/dist/LICENSE.txt

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