crewly 1.5.22 → 1.6.0

package/dist/cli/backend/src/types/credential.types.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Credential System Types
+ *
+ * Workspace-level credential store. Credentials (API keys, OAuth tokens) are
+ * decoupled from skills: skills declare slots, users add named credentials,
+ * agents bind specific credentials to slots at execution time.
+ *
+ * Registry entries are safe to show to LLM/agent contexts. Encrypted
+ * payloads (containing real token values) are never exposed to the agent —
+ * they are read only by the credential helper and by the skill executor
+ * for env-var injection into subprocesses.
+ *
+ * @module types/credential.types
+ */
+/**
+ * High-level type of credential — determines which payload schema is used
+ * and which helper (if any) owns the refresh lifecycle.
+ */
+export type CredentialType = 'api-key' | 'google-oauth';
+/**
+ * Lifecycle status of a credential.
+ *
+ * - `active`: usable; refresh tokens are valid
+ * - `revoked`: underlying refresh token no longer works. User must re-authorize.
+ */
+export type CredentialStatus = 'active' | 'revoked';
+/**
+ * Identifier for the helper responsible for token acquisition and refresh.
+ *
+ * - `gemini-cli-workspace`: piggybacks on user's Gemini CLI Workspace extension (Phase 1)
+ * - `byo-oauth`: user's own registered GCP OAuth client (Phase 2)
+ * - `gcloud-adc`: Google Cloud Application Default Credentials (Phase 2)
+ * - `crewly-official`: Crewly's published OAuth app (Phase 3)
+ */
+export type CredentialHelperName = 'gemini-cli-workspace' | 'byo-oauth' | 'gcloud-adc' | 'crewly-official';
+/**
+ * Public metadata for a credential. Never contains secret material.
+ * This is the exact shape exposed to agents / LLM contexts.
+ */
+export interface CredentialRegistryEntry {
+    /** UUID v4 — stable reference used everywhere (bindings, URLs, logs). */
+    id: string;
+    /** User-provided display name (e.g., "personal-gmail"). Not a reference. */
+    name: string;
+    /** Type discriminator — drives payload schema. */
+    type: CredentialType;
+    /** Provider identifier (e.g., "gemini", "google", "openai"). */
+    provider: string;
+    /** Helper that manages refresh (required for OAuth types). */
+    helper?: CredentialHelperName;
+    /** Granted OAuth scopes (OAuth types only). */
+    scopes?: string[];
+    /** Email address of the OAuth account — for user-visible display. */
+    accountEmail?: string;
+    /** ISO-8601 creation timestamp. */
+    createdAt: string;
+    /** ISO-8601 last metadata update. */
+    updatedAt: string;
+    /** ISO-8601 last injection into a skill run. */
+    lastUsedAt?: string;
+    /** Unix epoch ms when the current access token expires (OAuth only). */
+    expiresAt?: number;
+    /** Current status. */
+    status: CredentialStatus;
+    /** Relative path to the encrypted payload file (from credentials dir). */
+    encFile: string;
+}
+/**
+ * Registry file format stored at `~/.crewly/credentials/registry.json`.
+ */
+export interface CredentialRegistry {
+    schemaVersion: 1;
+    credentials: CredentialRegistryEntry[];
+}
+/**
+ * Payload for a static API key credential.
+ */
+export interface ApiKeyPayload {
+    type: 'api-key';
+    value: string;
+}
+/**
+ * Payload for a Google OAuth credential with refreshable access.
+ */
+export interface GoogleOAuthPayload {
+    type: 'google-oauth';
+    accessToken: string;
+    refreshToken: string;
+    tokenType: 'Bearer';
+    /** Unix epoch ms when accessToken expires. */
+    expiresAt: number;
+    /** Scopes granted by user consent. */
+    scopes: string[];
+    /** Account email (also denormalized into registry entry for display). */
+    accountEmail?: string;
+    /** OAuth client_id used to mint this grant (required for refresh). */
+    clientId: string;
+}
+/**
+ * Discriminated union over all payload variants. Switch on `type`.
+ */
+export type CredentialPayload = ApiKeyPayload | GoogleOAuthPayload;
+/**
+ * Concrete implementation of a credential helper strategy.
+ *
+ * Helpers are responsible for:
+ * - Returning a valid access token (refreshing if near expiry)
+ * - Recognizing `invalid_grant` / revocation and signalling via thrown error
+ *
+ * Implementations must be idempotent under concurrent calls for the same
+ * credential — the store's refresh manager wraps calls in a per-credential
+ * mutex, but helpers should not assume exclusive access across processes.
+ */
+export interface CredentialHelper {
+    readonly name: CredentialHelperName;
+    /**
+     * Return a valid access token for the given credential, refreshing if
+     * within the expiry buffer.
+     *
+     * @throws CredentialRevokedError if the refresh token is no longer valid
+     */
+    getAccessToken(entry: CredentialRegistryEntry, payload: GoogleOAuthPayload): Promise<GoogleOAuthPayload>;
+}
+/**
+ * A credential requirement declared in a SKILL.md frontmatter.
+ * Each requirement is a named "slot" the skill will read via an env var
+ * (`CREWLY_CRED_<SLOT>` for api-key, `CREWLY_CRED_<SLOT>_*` for OAuth).
+ */
+export interface SkillCredentialRequirement {
+    /** Slot name — used verbatim in env var prefix. Alphanumeric + hyphens. */
+    slot: string;
+    /** Credential type this slot expects. */
+    type: CredentialType;
+    /** Provider the skill expects (e.g., 'gemini', 'google'). */
+    provider: string;
+    /** Whether execution fails if no credential is bound to this slot. */
+    required: boolean;
+    /** UUID of a credential to use when no binding is supplied at runtime. */
+    default?: string;
+    /** OAuth scopes required for this slot (google-oauth only). */
+    requiredScopes?: string[];
+    /** Description shown in UI when selecting a credential for this slot. */
+    description?: string;
+}
+/**
+ * Runtime map from slot name to credential UUID, supplied by the agent in
+ * `execute_skill`. Overrides the skill's `default`.
+ */
+export type CredentialBindings = Record<string, string>;
+/**
+ * Thrown when a required slot has neither a binding nor a default.
+ */
+export declare class MissingCredentialError extends Error {
+    readonly slot: string;
+    readonly provider: string;
+    constructor(slot: string, provider: string);
+}
+/**
+ * Thrown when a bound credential's scopes do not cover the slot's requirements.
+ */
+export declare class InsufficientScopeError extends Error {
+    readonly slot: string;
+    readonly required: string[];
+    readonly granted: string[];
+    readonly missing: string[];
+    constructor(slot: string, required: string[], granted: string[]);
+}
+/**
+ * Thrown when an OAuth credential's refresh token is no longer valid.
+ * Carries the remediation string that callers (UI / agent) can surface to users.
+ */
+export declare class CredentialRevokedError extends Error {
+    readonly credentialId: string;
+    readonly credentialName: string;
+    readonly remediation: string;
+    constructor(credentialId: string, credentialName: string, remediation: string);
+}
+/**
+ * Thrown when a referenced credential id doesn't exist in the registry.
+ */
+export declare class CredentialNotFoundError extends Error {
+    readonly credentialId: string;
+    constructor(credentialId: string);
+}
+//# sourceMappingURL=credential.types.d.ts.map

package/dist/cli/backend/src/types/credential.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.types.d.ts","sourceRoot":"","sources":["../../../../../backend/src/types/credential.types.ts"],"names":[],"mappings":"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"}

package/dist/cli/backend/src/types/credential.types.js

@@ -0,0 +1,76 @@
+/**
+ * Credential System Types
+ *
+ * Workspace-level credential store. Credentials (API keys, OAuth tokens) are
+ * decoupled from skills: skills declare slots, users add named credentials,
+ * agents bind specific credentials to slots at execution time.
+ *
+ * Registry entries are safe to show to LLM/agent contexts. Encrypted
+ * payloads (containing real token values) are never exposed to the agent —
+ * they are read only by the credential helper and by the skill executor
+ * for env-var injection into subprocesses.
+ *
+ * @module types/credential.types
+ */
+// ============================================================================
+// Errors
+// ============================================================================
+/**
+ * Thrown when a required slot has neither a binding nor a default.
+ */
+export class MissingCredentialError extends Error {
+    slot;
+    provider;
+    constructor(slot, provider) {
+        super(`No credential bound to required slot '${slot}' (provider: ${provider})`);
+        this.slot = slot;
+        this.provider = provider;
+        this.name = 'MissingCredentialError';
+    }
+}
+/**
+ * Thrown when a bound credential's scopes do not cover the slot's requirements.
+ */
+export class InsufficientScopeError extends Error {
+    slot;
+    required;
+    granted;
+    missing;
+    constructor(slot, required, granted) {
+        const missing = required.filter((s) => !granted.includes(s));
+        super(`Credential for slot '${slot}' is missing scope(s): ${missing.join(', ')}`);
+        this.slot = slot;
+        this.required = required;
+        this.granted = granted;
+        this.name = 'InsufficientScopeError';
+        this.missing = missing;
+    }
+}
+/**
+ * Thrown when an OAuth credential's refresh token is no longer valid.
+ * Carries the remediation string that callers (UI / agent) can surface to users.
+ */
+export class CredentialRevokedError extends Error {
+    credentialId;
+    credentialName;
+    remediation;
+    constructor(credentialId, credentialName, remediation) {
+        super(`Credential '${credentialName}' (${credentialId}) is revoked. ${remediation}`);
+        this.credentialId = credentialId;
+        this.credentialName = credentialName;
+        this.remediation = remediation;
+        this.name = 'CredentialRevokedError';
+    }
+}
+/**
+ * Thrown when a referenced credential id doesn't exist in the registry.
+ */
+export class CredentialNotFoundError extends Error {
+    credentialId;
+    constructor(credentialId) {
+        super(`Credential not found: ${credentialId}`);
+        this.credentialId = credentialId;
+        this.name = 'CredentialNotFoundError';
+    }
+}
+//# sourceMappingURL=credential.types.js.map

package/dist/cli/backend/src/types/credential.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.types.js","sourceRoot":"","sources":["../../../../../backend/src/types/credential.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA4KH,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E;;GAEG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAE7B;IACA;IAFlB,YACkB,IAAY,EACZ,QAAgB;QAEhC,KAAK,CAAC,yCAAyC,IAAI,gBAAgB,QAAQ,GAAG,CAAC,CAAC;QAHhE,SAAI,GAAJ,IAAI,CAAQ;QACZ,aAAQ,GAAR,QAAQ,CAAQ;QAGhC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAI7B;IACA;IACA;IALF,OAAO,CAAW;IAElC,YACkB,IAAY,EACZ,QAAkB,EAClB,OAAiB;QAEjC,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,KAAK,CACH,wBAAwB,IAAI,0BAA0B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3E,CAAC;QAPc,SAAI,GAAJ,IAAI,CAAQ;QACZ,aAAQ,GAAR,QAAQ,CAAU;QAClB,YAAO,GAAP,OAAO,CAAU;QAMjC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAE7B;IACA;IACA;IAHlB,YACkB,YAAoB,EACpB,cAAsB,EACtB,WAAmB;QAEnC,KAAK,CACH,eAAe,cAAc,MAAM,YAAY,iBAAiB,WAAW,EAAE,CAC9E,CAAC;QANc,iBAAY,GAAZ,YAAY,CAAQ;QACpB,mBAAc,GAAd,cAAc,CAAQ;QACtB,gBAAW,GAAX,WAAW,CAAQ;QAKnC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACpB;IAA5B,YAA4B,YAAoB;QAC9C,KAAK,CAAC,yBAAyB,YAAY,EAAE,CAAC,CAAC;QADrB,iBAAY,GAAZ,YAAY,CAAQ;QAE9C,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF"}

package/dist/cli/backend/src/utils/encryption.utils.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Credential Encryption Utilities
+ *
+ * AES-256-GCM encryption with scrypt-derived keys for credential payloads.
+ * Uses a per-install master.key file (mode 0600) as the base key material.
+ *
+ * File format:
+ *   [1 byte: version=1] [12 bytes: IV] [16 bytes: auth tag] [N bytes: ciphertext]
+ *
+ * Threat model:
+ * - Primary defense: file exfiltration via backup / cloud sync / screen capture
+ * - NOT a defense against a compromised local user account or malicious code
+ *   running as the user (both can read master.key and derive the same key)
+ *
+ * @module utils/encryption.utils
+ */
+/**
+ * Clear the derived-key cache. Primarily for tests — production code should
+ * not need this as master.key is assumed stable for the process lifetime.
+ */
+export declare function _resetDerivedKeyCache(): void;
+/**
+ * Ensure a master.key file exists at the given path. If absent, generate
+ * a cryptographically random 32-byte key and write it with mode 0600.
+ *
+ * Idempotent: if the file already exists, does nothing.
+ *
+ * @param masterKeyPath - Absolute path to the master.key file
+ */
+export declare function ensureMasterKey(masterKeyPath: string): Promise<void>;
+/**
+ * Encrypt a UTF-8 string using AES-256-GCM.
+ *
+ * @param plaintext - The string to encrypt (caller typically JSON-serializes first)
+ * @param masterKeyPath - Absolute path to the master.key file
+ * @returns Buffer in the format `[version][iv][tag][ciphertext]`
+ */
+export declare function encrypt(plaintext: string, masterKeyPath: string): Promise<Buffer>;
+/**
+ * Decrypt a buffer produced by `encrypt()`.
+ *
+ * @param encrypted - Buffer in the `[version][iv][tag][ciphertext]` format
+ * @param masterKeyPath - Absolute path to the master.key file
+ * @returns The decrypted UTF-8 string
+ * @throws Error if the buffer is malformed, the version is unsupported,
+ *         or the auth tag does not match (tampering or wrong key)
+ */
+export declare function decrypt(encrypted: Buffer, masterKeyPath: string): Promise<string>;
+/**
+ * Default credentials directory: `~/.crewly/credentials/`.
+ */
+export declare function defaultCredentialsDir(): string;
+/**
+ * Default master.key path: `~/.crewly/credentials/master.key`.
+ */
+export declare function defaultMasterKeyPath(): string;
+//# sourceMappingURL=encryption.utils.d.ts.map

package/dist/cli/backend/src/utils/encryption.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.utils.d.ts","sourceRoot":"","sources":["../../../../../backend/src/utils/encryption.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAmEH;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU1E;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC3B,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAC3B,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,CA0BjB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}

package/dist/cli/backend/src/utils/encryption.utils.js

@@ -0,0 +1,162 @@
+/**
+ * Credential Encryption Utilities
+ *
+ * AES-256-GCM encryption with scrypt-derived keys for credential payloads.
+ * Uses a per-install master.key file (mode 0600) as the base key material.
+ *
+ * File format:
+ *   [1 byte: version=1] [12 bytes: IV] [16 bytes: auth tag] [N bytes: ciphertext]
+ *
+ * Threat model:
+ * - Primary defense: file exfiltration via backup / cloud sync / screen capture
+ * - NOT a defense against a compromised local user account or malicious code
+ *   running as the user (both can read master.key and derive the same key)
+ *
+ * @module utils/encryption.utils
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+/** File-format version byte — bump if layout changes. */
+const FORMAT_VERSION = 1;
+/** AES-256-GCM uses 12-byte (96-bit) IVs per NIST recommendation. */
+const IV_LENGTH = 12;
+/** AES-GCM produces 16-byte (128-bit) auth tags. */
+const AUTH_TAG_LENGTH = 16;
+/** AES-256 key size. */
+const KEY_LENGTH = 32;
+/** scrypt N (iteration count). 2^15 = 32768. */
+const SCRYPT_N = 32768;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+/**
+ * scrypt memory cap. Default in Node is 32MB which is right at the edge for
+ * our parameters; give explicit headroom so derivation never fails.
+ */
+const SCRYPT_MAX_MEM = 128 * 1024 * 1024;
+/** Fixed salt — changing invalidates all previously encrypted credentials. */
+const SCRYPT_SALT = Buffer.from('crewly-credentials-v1', 'utf8');
+/**
+ * Module-level cache of derived keys, keyed by master.key path. scrypt is
+ * intentionally expensive (~100ms per call), so we run it once per master
+ * key path per process. Concurrent callers share the in-flight promise.
+ */
+const derivedKeyCache = new Map();
+/**
+ * Derive the AES key from the master.key file contents via scrypt. Results
+ * are cached by master-key path for the lifetime of the process.
+ *
+ * @param masterKeyPath - Absolute path to the master.key file
+ * @returns A 32-byte derived key
+ */
+async function deriveKey(masterKeyPath) {
+    const cached = derivedKeyCache.get(masterKeyPath);
+    if (cached)
+        return cached;
+    const promise = deriveKeyUncached(masterKeyPath).catch((err) => {
+        // On failure, remove the rejected promise so the next call retries.
+        derivedKeyCache.delete(masterKeyPath);
+        throw err;
+    });
+    derivedKeyCache.set(masterKeyPath, promise);
+    return promise;
+}
+async function deriveKeyUncached(masterKeyPath) {
+    const masterKey = await fs.readFile(masterKeyPath);
+    return new Promise((resolve, reject) => {
+        crypto.scrypt(masterKey, SCRYPT_SALT, KEY_LENGTH, { N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P, maxmem: SCRYPT_MAX_MEM }, (err, derivedKey) => (err ? reject(err) : resolve(derivedKey)));
+    });
+}
+/**
+ * Clear the derived-key cache. Primarily for tests — production code should
+ * not need this as master.key is assumed stable for the process lifetime.
+ */
+export function _resetDerivedKeyCache() {
+    derivedKeyCache.clear();
+}
+/**
+ * Ensure a master.key file exists at the given path. If absent, generate
+ * a cryptographically random 32-byte key and write it with mode 0600.
+ *
+ * Idempotent: if the file already exists, does nothing.
+ *
+ * @param masterKeyPath - Absolute path to the master.key file
+ */
+export async function ensureMasterKey(masterKeyPath) {
+    try {
+        await fs.access(masterKeyPath);
+        return;
+    }
+    catch {
+        // File doesn't exist — create it.
+    }
+    await fs.mkdir(path.dirname(masterKeyPath), { recursive: true });
+    const key = crypto.randomBytes(32);
+    await fs.writeFile(masterKeyPath, key, { mode: 0o600 });
+}
+/**
+ * Encrypt a UTF-8 string using AES-256-GCM.
+ *
+ * @param plaintext - The string to encrypt (caller typically JSON-serializes first)
+ * @param masterKeyPath - Absolute path to the master.key file
+ * @returns Buffer in the format `[version][iv][tag][ciphertext]`
+ */
+export async function encrypt(plaintext, masterKeyPath) {
+    const key = await deriveKey(masterKeyPath);
+    const iv = crypto.randomBytes(IV_LENGTH);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const ciphertext = Buffer.concat([
+        cipher.update(plaintext, 'utf8'),
+        cipher.final(),
+    ]);
+    const authTag = cipher.getAuthTag();
+    return Buffer.concat([
+        Buffer.from([FORMAT_VERSION]),
+        iv,
+        authTag,
+        ciphertext,
+    ]);
+}
+/**
+ * Decrypt a buffer produced by `encrypt()`.
+ *
+ * @param encrypted - Buffer in the `[version][iv][tag][ciphertext]` format
+ * @param masterKeyPath - Absolute path to the master.key file
+ * @returns The decrypted UTF-8 string
+ * @throws Error if the buffer is malformed, the version is unsupported,
+ *         or the auth tag does not match (tampering or wrong key)
+ */
+export async function decrypt(encrypted, masterKeyPath) {
+    if (encrypted.length < 1 + IV_LENGTH + AUTH_TAG_LENGTH + 1) {
+        throw new Error('Encrypted buffer is too short to be valid');
+    }
+    const version = encrypted[0];
+    if (version !== FORMAT_VERSION) {
+        throw new Error(`Unsupported encryption format version: ${version}`);
+    }
+    const iv = encrypted.subarray(1, 1 + IV_LENGTH);
+    const authTag = encrypted.subarray(1 + IV_LENGTH, 1 + IV_LENGTH + AUTH_TAG_LENGTH);
+    const ciphertext = encrypted.subarray(1 + IV_LENGTH + AUTH_TAG_LENGTH);
+    const key = await deriveKey(masterKeyPath);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(authTag);
+    const plaintext = Buffer.concat([
+        decipher.update(ciphertext),
+        decipher.final(),
+    ]);
+    return plaintext.toString('utf8');
+}
+/**
+ * Default credentials directory: `~/.crewly/credentials/`.
+ */
+export function defaultCredentialsDir() {
+    return path.join(os.homedir(), '.crewly', 'credentials');
+}
+/**
+ * Default master.key path: `~/.crewly/credentials/master.key`.
+ */
+export function defaultMasterKeyPath() {
+    return path.join(defaultCredentialsDir(), 'master.key');
+}
+//# sourceMappingURL=encryption.utils.js.map

package/dist/cli/backend/src/utils/encryption.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.utils.js","sourceRoot":"","sources":["../../../../../backend/src/utils/encryption.utils.ts"],"names":[],"mappings":"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"}

package/dist/cli/backend/src/utils/skill-md-parser.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SKILL.md Parser
+ *
+ * Parses SKILL.md files containing YAML frontmatter and Markdown body.
+ * Used by SkillService and SkillCatalogService to load skill definitions
+ * from the new SKILL.md format (replacing skill.json + instructions.md).
+ *
+ * @module utils/skill-md-parser
+ */
+/**
+ * Result of parsing a SKILL.md file.
+ */
+export interface SkillMdParseResult {
+    /** Parsed YAML frontmatter as a plain object */
+    frontmatter: Record<string, unknown>;
+    /** Markdown body content after the frontmatter */
+    body: string;
+}
+/**
+ * Parse a SKILL.md file's content into frontmatter and body.
+ *
+ * Expects the format:
+ * ```
+ * ---
+ * name: Skill Name
+ * description: What it does
+ * ...
+ * ---
+ *
+ * # Markdown body here
+ * ```
+ *
+ * @param content - Raw content of the SKILL.md file
+ * @returns Parsed frontmatter object and markdown body
+ * @throws Error if frontmatter delimiters are missing or YAML is invalid
+ */
+export declare function parseSkillMd(content: string): SkillMdParseResult;
+//# sourceMappingURL=skill-md-parser.d.ts.map

package/dist/cli/backend/src/utils/skill-md-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-md-parser.d.ts","sourceRoot":"","sources":["../../../../../backend/src/utils/skill-md-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAuBhE"}

package/dist/cli/backend/src/utils/skill-md-parser.js

@@ -0,0 +1,47 @@
+/**
+ * SKILL.md Parser
+ *
+ * Parses SKILL.md files containing YAML frontmatter and Markdown body.
+ * Used by SkillService and SkillCatalogService to load skill definitions
+ * from the new SKILL.md format (replacing skill.json + instructions.md).
+ *
+ * @module utils/skill-md-parser
+ */
+import { parse as parseYAML } from 'yaml';
+/**
+ * Parse a SKILL.md file's content into frontmatter and body.
+ *
+ * Expects the format:
+ * ```
+ * ---
+ * name: Skill Name
+ * description: What it does
+ * ...
+ * ---
+ *
+ * # Markdown body here
+ * ```
+ *
+ * @param content - Raw content of the SKILL.md file
+ * @returns Parsed frontmatter object and markdown body
+ * @throws Error if frontmatter delimiters are missing or YAML is invalid
+ */
+export function parseSkillMd(content) {
+    const trimmed = content.trimStart();
+    if (!trimmed.startsWith('---')) {
+        throw new Error('SKILL.md missing opening frontmatter delimiter (---)');
+    }
+    // Find the closing --- delimiter (skip the first one)
+    const closingIndex = trimmed.indexOf('\n---', 3);
+    if (closingIndex === -1) {
+        throw new Error('SKILL.md missing closing frontmatter delimiter (---)');
+    }
+    const yamlContent = trimmed.slice(4, closingIndex); // skip opening "---\n"
+    const body = trimmed.slice(closingIndex + 4).trim(); // skip "\n---"
+    const frontmatter = parseYAML(yamlContent);
+    if (!frontmatter || typeof frontmatter !== 'object') {
+        throw new Error('SKILL.md frontmatter is not a valid YAML object');
+    }
+    return { frontmatter, body };
+}
+//# sourceMappingURL=skill-md-parser.js.map

package/dist/cli/backend/src/utils/skill-md-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-md-parser.js","sourceRoot":"","sources":["../../../../../backend/src/utils/skill-md-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAY1C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAEpC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IAED,sDAAsD;IACtD,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACjD,IAAI,YAAY,KAAK,CAAC,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IAED,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,uBAAuB;IAC3E,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,eAAe;IAEpE,MAAM,WAAW,GAAG,SAAS,CAAC,WAAW,CAA4B,CAAC;IAEtE,IAAI,CAAC,WAAW,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AAC/B,CAAC"}