@prave/shared 1.2.2 → 1.4.0

package/dist/lib/compile-skill.d.ts

@@ -0,0 +1,54 @@
+import type { AgentType } from '../types/intelligence.js';
+/**
+ * compileSkill — convert a single canonical `SKILL.md` body into the
+ * exact file shape each supported agent expects.
+ *
+ * Why this lives in `@prave/shared`:
+ *   - The CLI's `prave deploy` writes the converted file straight to
+ *     the agent's local directory.
+ *   - The SaaS `/dashboard/compile` page bundles converted files into
+ *     a zip download.
+ *   - Both need byte-identical output, otherwise users see drift
+ *     between "what `prave deploy` puts on disk" and "what the
+ *     compile page generates". Putting the converters in a shared
+ *     package is the only way to guarantee that.
+ *
+ * Per-agent conversion rules (current 6 supported, others stubbed):
+ *
+ *   claude / cline / amp / gemini / codex
+ *     Identity transform. The canonical SKILL.md format IS the
+ *     Anthropic skill format; these agents either use it natively or
+ *     accept it via a `~/.<agent>/skills/<slug>/SKILL.md` directory
+ *     convention. Returned `relPath`s mirror that layout.
+ *
+ *   cursor
+ *     Cursor's rules format is `.cursor/rules/<slug>.mdc` with
+ *     frontmatter `globs:` instead of `triggers:`. We rename the key
+ *     when frontmatter is present; when absent, we synthesize a
+ *     minimal frontmatter block so the .mdc file parses cleanly. The
+ *     body is left untouched.
+ *
+ * The `path` returned is a **POSIX-style relative path** rooted at the
+ * agent's install dir. The CLI joins it onto the expanded `basePath`
+ * (e.g. `~/.claude/skills/`); the web zip uses it as the in-archive
+ * path. Never absolute, never platform-specific separators — that's
+ * the caller's job.
+ */
+export interface CompiledArtifact {
+    agent: AgentType;
+    /** Relative path within the agent's install root. POSIX separators. */
+    path: string;
+    /** File body to write at `path`. UTF-8 text. */
+    content: string;
+    /**
+     * `true` when the body was rewritten (frontmatter rename, key
+     * synthesis, format mutation). UI surfaces this as a small
+     * "converted" badge so users know the agent gets a non-canonical
+     * shape. `false` for identity-transformed agents.
+     */
+    converted: boolean;
+}
+export declare function compileSkill(content: string, slug: string, agent: AgentType): CompiledArtifact;
+/** Bundle helper — compile a skill for many agents in one pass. */
+export declare function compileSkillBundle(content: string, slug: string, agents: ReadonlyArray<AgentType>): CompiledArtifact[];
+//# sourceMappingURL=compile-skill.d.ts.map

package/dist/lib/compile-skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-skill.d.ts","sourceRoot":"","sources":["../../src/lib/compile-skill.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,SAAS,CAAA;IAChB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAA;IACZ,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,SAAS,GACf,gBAAgB,CAWlB;AAED,mEAAmE;AACnE,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,GAC/B,gBAAgB,EAAE,CAEpB"}

package/dist/lib/compile-skill.js

@@ -0,0 +1,52 @@
+export function compileSkill(content, slug, agent) {
+    switch (agent) {
+        case 'cursor':
+            return compileCursor(content, slug);
+        case 'claude':
+        case 'codex':
+        case 'gemini':
+        case 'cline':
+        case 'amp':
+            return compileIdentity(content, slug, agent);
+    }
+}
+/** Bundle helper — compile a skill for many agents in one pass. */
+export function compileSkillBundle(content, slug, agents) {
+    return agents.map((a) => compileSkill(content, slug, a));
+}
+/* ─── per-agent converters ─────────────────────────────────────── */
+function compileIdentity(content, slug, agent) {
+    return {
+        agent,
+        path: `${slug}/SKILL.md`,
+        content,
+        converted: false,
+    };
+}
+function compileCursor(content, slug) {
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?/);
+    let out;
+    if (fmMatch && fmMatch[1] !== undefined) {
+        const body = content.slice(fmMatch[0].length);
+        // Cursor's spec uses `globs:` not `triggers:`. Other fields
+        // (name, description, tags) pass through unchanged. We rename
+        // line-anchored so a `triggers:` substring inside an example
+        // code block in the body isn't accidentally rewritten.
+        const fmInner = fmMatch[1].replace(/(^|\n)triggers:/g, '$1globs:');
+        out = `---\n${fmInner}\n---\n${body}`;
+    }
+    else {
+        // No frontmatter at all — synthesize a minimal one from the slug
+        // and the first non-blank line of the body. Cursor refuses .mdc
+        // files without frontmatter, so this is the difference between
+        // a working rule and a broken one.
+        const firstLine = content.trim().replace(/\s+/g, ' ').slice(0, 200);
+        out = `---\nname: ${slug}\ndescription: ${firstLine}\n---\n${content}`;
+    }
+    return {
+        agent: 'cursor',
+        path: `.cursor/rules/${slug}.mdc`,
+        content: out,
+        converted: true,
+    };
+}

package/dist/lib/index.d.ts

@@ -1,2 +1,4 @@
 export * from './classify.js';
+export * from './compile-skill.js';
+export * from './secret-scanner.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA"}

package/dist/lib/index.js

@@ -1 +1,3 @@
 export * from './classify.js';
+export * from './compile-skill.js';
+export * from './secret-scanner.js';

package/dist/lib/secret-scanner.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Secret-scanner — shared pre-insert gate for skill bundles.
+ *
+ * Two layers:
+ *
+ *   1. **Path patterns** — file names / paths that are categorically
+ *      forbidden in a public-facing skill bundle. Hits are an immediate
+ *      reject, no content peek needed.
+ *
+ *   2. **Content regexes** — high-confidence credential shapes that
+ *      stand out even inside a text body. We only run these against
+ *      files that look like text (we don't want to false-match a key
+ *      shape inside a compressed binary blob).
+ *
+ * The scanner is called from two places:
+ *
+ *   • `apps/worker/src/jobs/scan-github-repo.job.ts` — silent reject,
+ *     bundle is marked 'rejected' and never surfaces in the catalogue.
+ *   • `apps/api/src/services/bundle-storage.service.ts` — surfaces the
+ *     finding back to the user so they can scrub the file and re-deploy.
+ *
+ * Same code, two failure modes. Keep this file dependency-free so the
+ * worker (Node) and the API (Node) and a future web-side validator
+ * (browser) can all run it without bundling friction.
+ */
+export interface SecretFinding {
+    /** Path of the offending file within the bundle. */
+    path: string;
+    /** Short identifier of the rule that fired (`env-file`, `aws-key`, …). */
+    rule: string;
+    /**
+     * 1-indexed line where the match was found, when a content regex
+     * fired. Omitted for path-based rejects.
+     */
+    line?: number;
+}
+export interface SecretScanInput {
+    /** File path relative to the bundle root, e.g. `scripts/post.ts`. */
+    path: string;
+    /** File content as a UTF-8 string. NULL/undefined for binary files. */
+    content?: string | null;
+}
+export interface SecretScanResult {
+    /** Final verdict. `clean` means the bundle is safe to expose / run. */
+    status: 'clean' | 'rejected';
+    /** Every triggered rule. Empty when `status === 'clean'`. */
+    findings: SecretFinding[];
+}
+/**
+ * Run both layers across a list of files. Returns a verdict + every
+ * matching rule across every file. Empty findings = clean bundle.
+ *
+ * Files where `content` is missing skip the content-regex stage but
+ * still trip path rules.
+ */
+export declare function scanForSecrets(files: SecretScanInput[]): SecretScanResult;
+/**
+ * Whether a path likely points at a text-readable file (worth running
+ * content regexes against). Used by callers to filter the input list
+ * before they bother loading binary blobs.
+ */
+export declare function isLikelyTextPath(path: string): boolean;
+//# sourceMappingURL=secret-scanner.d.ts.map

package/dist/lib/secret-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-scanner.d.ts","sourceRoot":"","sources":["../../src/lib/secret-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAA;IACZ,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,MAAM,EAAE,OAAO,GAAG,UAAU,CAAA;IAC5B,6DAA6D;IAC7D,QAAQ,EAAE,aAAa,EAAE,CAAA;CAC1B;AAwGD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,gBAAgB,CAmCzE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAStD"}

package/dist/lib/secret-scanner.js

@@ -0,0 +1,214 @@
+/**
+ * Secret-scanner — shared pre-insert gate for skill bundles.
+ *
+ * Two layers:
+ *
+ *   1. **Path patterns** — file names / paths that are categorically
+ *      forbidden in a public-facing skill bundle. Hits are an immediate
+ *      reject, no content peek needed.
+ *
+ *   2. **Content regexes** — high-confidence credential shapes that
+ *      stand out even inside a text body. We only run these against
+ *      files that look like text (we don't want to false-match a key
+ *      shape inside a compressed binary blob).
+ *
+ * The scanner is called from two places:
+ *
+ *   • `apps/worker/src/jobs/scan-github-repo.job.ts` — silent reject,
+ *     bundle is marked 'rejected' and never surfaces in the catalogue.
+ *   • `apps/api/src/services/bundle-storage.service.ts` — surfaces the
+ *     finding back to the user so they can scrub the file and re-deploy.
+ *
+ * Same code, two failure modes. Keep this file dependency-free so the
+ * worker (Node) and the API (Node) and a future web-side validator
+ * (browser) can all run it without bundling friction.
+ */
+// ── Path patterns ────────────────────────────────────────────────────
+// Matched against the lowercased file path. Anchored at the basename
+// where it makes sense (`.env`) and as substring elsewhere (`secrets/`).
+const PATH_RULES = [
+    {
+        rule: 'env-file',
+        test: (p) => {
+            const base = basename(p);
+            // .env, .env.local, .env.production, .envrc — but NOT .env.example
+            // or .env.sample (templates are encouraged).
+            if (base === '.env' || base.startsWith('.env.')) {
+                return !/\.(example|sample|template)$/.test(base);
+            }
+            if (base === '.envrc')
+                return true;
+            return false;
+        },
+    },
+    {
+        rule: 'private-key',
+        test: (p) => /\.(pem|p12|pfx|key|jks)$/i.test(p),
+    },
+    {
+        rule: 'ssh-private-key',
+        test: (p) => {
+            const base = basename(p);
+            return /^id_(rsa|ecdsa|ed25519|dsa)$/.test(base);
+        },
+    },
+    {
+        rule: 'gcp-service-account',
+        test: (p) => {
+            const base = basename(p).toLowerCase();
+            return (base === 'service-account.json' ||
+                /^service-account[-_].*\.json$/.test(base) ||
+                base === 'gcp-key.json' ||
+                base === 'firebase-adminsdk.json');
+        },
+    },
+    {
+        rule: 'aws-credentials',
+        test: (p) => {
+            const lower = p.toLowerCase();
+            return (lower.endsWith('/.aws/credentials') ||
+                lower === '.aws/credentials' ||
+                lower.endsWith('aws-credentials.json'));
+        },
+    },
+    {
+        rule: 'credentials-file',
+        test: (p) => {
+            const base = basename(p).toLowerCase();
+            return (base === 'credentials.json' ||
+                base === 'secrets.json' ||
+                base === 'secret.json');
+        },
+    },
+    {
+        rule: 'secrets-dir',
+        test: (p) => /(^|\/)secrets\//i.test(p),
+    },
+];
+// ── Content regexes ──────────────────────────────────────────────────
+// High-confidence shapes only — false positives mean a frustrated user
+// re-uploading after a scrub they couldn't validate. Keep the bar high.
+const CONTENT_RULES = [
+    // Anthropic
+    { rule: 'anthropic-api-key', regex: /\bsk-ant-[a-zA-Z0-9-_]{20,}\b/ },
+    // OpenAI
+    { rule: 'openai-api-key', regex: /\bsk-(?:proj-)?[a-zA-Z0-9-_]{32,}\b/ },
+    // AWS
+    { rule: 'aws-access-key-id', regex: /\bAKIA[0-9A-Z]{16}\b/ },
+    { rule: 'aws-secret-access-key', regex: /aws_secret_access_key\s*=\s*['"]?[A-Za-z0-9/+=]{40}\b/i },
+    // GitHub
+    { rule: 'github-personal-token', regex: /\bghp_[A-Za-z0-9]{36}\b/ },
+    { rule: 'github-oauth-token', regex: /\bgho_[A-Za-z0-9]{36}\b/ },
+    { rule: 'github-fine-grained-token', regex: /\bgithub_pat_[A-Za-z0-9_]{82}\b/ },
+    // Stripe
+    { rule: 'stripe-live-key', regex: /\bsk_live_[A-Za-z0-9]{24,}\b/ },
+    { rule: 'stripe-restricted-key', regex: /\brk_live_[A-Za-z0-9]{24,}\b/ },
+    // Google API key
+    { rule: 'google-api-key', regex: /\bAIza[0-9A-Za-z\-_]{35}\b/ },
+    // Slack
+    { rule: 'slack-bot-token', regex: /\bxoxb-[A-Za-z0-9-]{20,}\b/ },
+    { rule: 'slack-user-token', regex: /\bxoxp-[A-Za-z0-9-]{20,}\b/ },
+    // GitLab
+    { rule: 'gitlab-personal-token', regex: /\bglpat-[A-Za-z0-9_-]{20}\b/ },
+    // Supabase / JWT-shaped service-role key (the shape, not the host).
+    // Has 3 base64url segments separated by '.'. We require an `eyJ`
+    // header (RFC 7519 typ:"JWT") to dodge random base64 strings.
+    {
+        rule: 'jwt-token',
+        regex: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/,
+    },
+];
+/**
+ * Run both layers across a list of files. Returns a verdict + every
+ * matching rule across every file. Empty findings = clean bundle.
+ *
+ * Files where `content` is missing skip the content-regex stage but
+ * still trip path rules.
+ */
+export function scanForSecrets(files) {
+    const findings = [];
+    for (const file of files) {
+        // Path-based rules
+        for (const { rule, test } of PATH_RULES) {
+            if (test(file.path)) {
+                findings.push({ path: file.path, rule });
+            }
+        }
+        // Content-based rules — only on text. We could be smarter (e.g.
+        // skip files >1MB) but the worker already caps bundle size and
+        // skips known-binary extensions before getting here.
+        if (typeof file.content === 'string' && file.content.length > 0) {
+            // Split once for line numbers; the regex tests run against the
+            // full body so multiline shapes still match.
+            const lines = file.content.split('\n');
+            for (const { rule, regex } of CONTENT_RULES) {
+                // Reset stateful regexes — we don't use /g but be defensive.
+                const localRegex = new RegExp(regex.source, regex.flags.replace('g', ''));
+                for (let i = 0; i < lines.length; i++) {
+                    if (localRegex.test(lines[i] ?? '')) {
+                        findings.push({ path: file.path, rule, line: i + 1 });
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    return {
+        status: findings.length > 0 ? 'rejected' : 'clean',
+        findings,
+    };
+}
+/**
+ * Whether a path likely points at a text-readable file (worth running
+ * content regexes against). Used by callers to filter the input list
+ * before they bother loading binary blobs.
+ */
+export function isLikelyTextPath(path) {
+    const ext = path.toLowerCase().split('.').pop() ?? '';
+    return (TEXT_EXTENSIONS.has(ext) ||
+        // Files without an extension that we'd still want to scan
+        path.endsWith('Dockerfile') ||
+        path.endsWith('Makefile') ||
+        /\.env(\.|$)/.test(path));
+}
+const TEXT_EXTENSIONS = new Set([
+    'md',
+    'mdx',
+    'txt',
+    'json',
+    'yaml',
+    'yml',
+    'toml',
+    'ini',
+    'cfg',
+    'conf',
+    'env',
+    'js',
+    'jsx',
+    'ts',
+    'tsx',
+    'mjs',
+    'cjs',
+    'py',
+    'rb',
+    'go',
+    'rs',
+    'sh',
+    'bash',
+    'zsh',
+    'fish',
+    'sql',
+    'graphql',
+    'gql',
+    'html',
+    'xml',
+    'svg',
+    'css',
+    'scss',
+    'less',
+    'lock',
+]);
+function basename(p) {
+    const i = p.lastIndexOf('/');
+    return i === -1 ? p : p.slice(i + 1);
+}

package/dist/schemas/index.d.ts

@@ -14,4 +14,5 @@ export * from './skill-pr.schema.js';
 export * from './intelligence.schema.js';
 export * from './api-keys.schema.js';
 export * from './skill-report.schema.js';
+export * from './run.schema.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/schemas/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,mBAAmB,CAAA;AACjC,cAAc,2BAA2B,CAAA;AACzC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,mBAAmB,CAAA;AACjC,cAAc,2BAA2B,CAAA;AACzC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,wBAAwB,CAAA;AACtC,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,iBAAiB,CAAA"}

package/dist/schemas/index.js

@@ -14,3 +14,4 @@ export * from './skill-pr.schema.js';
 export * from './intelligence.schema.js';
 export * from './api-keys.schema.js';
 export * from './skill-report.schema.js';
+export * from './run.schema.js';