@moda-ai/cli 1.10.2 → 1.12.0

package/dist/skills-bundled.d.ts

@@ -0,0 +1,35 @@
+export interface BundledSkillIndexEntry {
+    id: string;
+    version: string;
+    summary: string;
+    targets: {
+        language: string;
+        frameworks: string[];
+        providers: string[];
+    };
+}
+export interface BundledSkillIndex {
+    schema_version: string;
+    bundled_at: string;
+    cli_version: string;
+    skills: BundledSkillIndexEntry[];
+}
+export interface IntegrationSkillInstallResult {
+    skillId: string;
+    status: 'installed' | 'unchanged';
+    paths: string[];
+}
+/** Directory holding the bundled skills (overridable for tests). */
+export declare function bundledSkillsDir(): string;
+/** Read the bundled skill menu, or null when no bundle is present. */
+export declare function readBundledIndex(): BundledSkillIndex | null;
+/** Read a bundled skill's SKILL.md, or null when it is not bundled. */
+export declare function readBundledSkillMd(skillId: string): string | null;
+/**
+ * Materialize a bundled integration skill into the project.
+ *
+ * Idempotent: unchanged files are left untouched, and a second install with
+ * identical content reports status 'unchanged' without writing.
+ */
+export declare function installIntegrationSkill(skillId: string, cwd?: string): IntegrationSkillInstallResult;
+//# sourceMappingURL=skills-bundled.d.ts.map

package/dist/skills-bundled.js

@@ -0,0 +1,157 @@
+// src/skills-bundled.ts — read and materialize the integration skills bundled
+// inside the npm package (skills/integration/, generated at build time by
+// scripts/bundle-skills.ts from packages/integration-skills/).
+//
+// Materialization copies the full skill directory (SKILL.md, EXAMPLE.md,
+// references/) into the project's .claude/skills/<id>/, translates SKILL.md
+// into a Cursor rule when the project uses Cursor, and records the install in
+// .moda/skills.yml with source: integration-bundled so `skills sync` never
+// pushes these files and harness release changes never prune them.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { claudeSkillToCursorRule } from './init/rules.js';
+import { detectAgents } from './init/mcp.js';
+import { readSkillsManifest, SKILL_SOURCE_INTEGRATION_BUNDLED, upsertSkillManifestRecord, } from './skills-manifest.js';
+// Resolved relative to this module so it works from src/ in dev and from the
+// published dist/ inside node_modules (same pattern as src/init/rules.ts).
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const BUNDLED_SKILLS_DIR = join(PACKAGE_ROOT, 'skills', 'integration');
+/** Directory holding the bundled skills (overridable for tests). */
+export function bundledSkillsDir() {
+    return process.env.MODA_BUNDLED_SKILLS_DIR || BUNDLED_SKILLS_DIR;
+}
+/** Read the bundled skill menu, or null when no bundle is present. */
+export function readBundledIndex() {
+    const indexPath = join(bundledSkillsDir(), 'index.json');
+    if (!existsSync(indexPath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(indexPath, 'utf8'));
+        if (!Array.isArray(parsed.skills))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read a bundled skill's SKILL.md, or null when it is not bundled. */
+export function readBundledSkillMd(skillId) {
+    const path = join(bundledSkillsDir(), skillId, 'SKILL.md');
+    if (!existsSync(path))
+        return null;
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Materialize a bundled integration skill into the project.
+ *
+ * Idempotent: unchanged files are left untouched, and a second install with
+ * identical content reports status 'unchanged' without writing.
+ */
+export function installIntegrationSkill(skillId, cwd = process.cwd()) {
+    if (!/^[a-z0-9-]+$/.test(skillId)) {
+        throw new Error(`Invalid integration skill id: ${JSON.stringify(skillId).slice(0, 80)}`);
+    }
+    const sourceDir = join(bundledSkillsDir(), skillId);
+    if (!existsSync(join(sourceDir, 'SKILL.md'))) {
+        const bundled = readBundledIndex()?.skills.map((skill) => skill.id) ?? [];
+        throw new Error(`Integration skill '${skillId}' is not bundled with this CLI.${bundled.length > 0 ? ` Bundled skills: ${bundled.join(', ')}` : ''}`);
+    }
+    const files = listFilesRecursive(sourceDir).sort();
+    // Plan every write up front (skill files + optional Cursor rule) so the
+    // ownership guard can reject the whole install before touching disk.
+    const plannedWrites = [];
+    for (const file of files) {
+        const relPath = relative(sourceDir, file).replace(/\\/g, '/');
+        plannedWrites.push({
+            targetRelPath: `.claude/skills/${skillId}/${relPath}`,
+            targetPath: join(cwd, '.claude', 'skills', skillId, relPath),
+            content: readFileSync(file, 'utf8'),
+        });
+    }
+    // Cursor translation of the entry point, when the project uses Cursor.
+    const writeCursor = detectAgents().includes('Cursor') || existsSync(join(cwd, '.cursor'));
+    if (writeCursor) {
+        const skillMd = readFileSync(join(sourceDir, 'SKILL.md'), 'utf8');
+        plannedWrites.push({
+            targetRelPath: `.cursor/rules/${skillId}.mdc`,
+            targetPath: join(cwd, '.cursor', 'rules', `${skillId}.mdc`),
+            content: claudeSkillToCursorRule(skillMd),
+        });
+    }
+    // Ownership guard: never clobber a file Moda does not already manage. A repo
+    // that happens to carry a user-authored .claude/skills/<id>/... or
+    // .cursor/rules/<id>.mdc at one of our target paths must not be silently
+    // overwritten. Paths recorded in .moda/skills.yml (any source) are ours, so
+    // idempotent re-installs still pass; only genuinely foreign files trip this.
+    const ownedPaths = new Set((readSkillsManifest(cwd)?.records ?? []).flatMap((record) => record.paths));
+    const collisions = plannedWrites.filter((write) => existsSync(write.targetPath) && !ownedPaths.has(write.targetRelPath));
+    if (collisions.length > 0) {
+        throw new Error(`Refusing to overwrite ${collisions.length} existing file(s) not managed by Moda: ` +
+            `${collisions.map((write) => write.targetRelPath).join(', ')}. ` +
+            'Move or remove them, then re-run to install the bundled integration skill.');
+    }
+    const paths = [];
+    let wroteAny = false;
+    for (const write of plannedWrites) {
+        if (writeIfChanged(write.targetPath, write.content))
+            wroteAny = true;
+        paths.push(write.targetRelPath);
+    }
+    upsertSkillManifestRecord(cwd, {
+        skillId,
+        contentHash: hashSkillDir(sourceDir, files),
+        source: SKILL_SOURCE_INTEGRATION_BUNDLED,
+        paths,
+    });
+    return { skillId, status: wroteAny ? 'installed' : 'unchanged', paths };
+}
+function writeIfChanged(path, content) {
+    if (existsSync(path)) {
+        try {
+            if (readFileSync(path, 'utf8') === content)
+                return false;
+        }
+        catch {
+            // Unreadable existing file: fall through and rewrite.
+        }
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+    return true;
+}
+function listFilesRecursive(dir) {
+    const files = [];
+    const stack = [dir];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            const path = join(current, entry.name);
+            if (entry.isDirectory())
+                stack.push(path);
+            else if (entry.isFile())
+                files.push(path);
+        }
+    }
+    return files;
+}
+function hashSkillDir(sourceDir, files) {
+    const hash = createHash('sha256');
+    for (const file of files) {
+        hash.update(relative(sourceDir, file).replace(/\\/g, '/'));
+        hash.update('\0');
+        hash.update(readFileSync(file));
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+//# sourceMappingURL=skills-bundled.js.map

package/dist/skills-manifest.d.ts

@@ -0,0 +1,33 @@
+export declare const SKILLS_MANIFEST_PATH: string;
+export declare const SKILL_SOURCE_HARNESS = "moda";
+export declare const SKILL_SOURCE_INTEGRATION_BUNDLED = "integration-bundled";
+export interface SkillInstallRecord {
+    skillId: string;
+    contentHash: string;
+    source: string;
+    paths: string[];
+}
+export interface ManifestHeader {
+    tenantId: string;
+    releaseKey: string;
+    statusFilter: string;
+    generationRunId: string;
+    generationVersion: number;
+    releasedAt: string;
+}
+export interface SkillsManifest extends ManifestHeader {
+    managedPaths: string[];
+    records: SkillInstallRecord[];
+}
+export declare function readSkillsManifest(cwd: string): SkillsManifest | null;
+export declare function manifestHeaderFrom(manifest: SkillsManifest | null): ManifestHeader;
+export declare function writeSkillsManifest(cwd: string, header: ManifestHeader, records: SkillInstallRecord[]): void;
+/**
+ * Upsert a skill record into .moda/skills.yml, preserving the harness release
+ * header and all other records. Used by the bundled integration-skill
+ * installer so its materialized files become managed paths (excluded from
+ * `skills sync`, never pruned by harness release changes).
+ */
+export declare function upsertSkillManifestRecord(cwd: string, record: SkillInstallRecord): void;
+export declare function pruneManagedSkillPaths(cwd: string, managedPaths: string[], log: (msg: string) => void): number;
+//# sourceMappingURL=skills-manifest.d.ts.map

package/dist/skills-manifest.js

@@ -0,0 +1,244 @@
+// src/skills-manifest.ts — the .moda/skills.yml install manifest.
+//
+// The manifest records every skill file Moda manages inside a user's repo so
+// that (a) `skills sync` never pushes Moda-managed files back up, and (b) a
+// harness release change prunes exactly the files the previous release wrote.
+// Two producers write records here: `skills pull` (harness-generated skills,
+// source 'moda') and the bundled integration-skill installer
+// (src/skills-bundled.ts, source 'integration-bundled').
+//
+// IMPORTANT: the YAML here is hand-rolled on both sides — writeSkillsManifest
+// emits a fixed 2/4/6-space layout and readSkillRecords/readManagedPaths parse
+// exactly that layout. Keep reader and writer in lockstep; they live in this
+// module together so a format change cannot land on one side only.
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { dirname, isAbsolute, join, normalize, relative, resolve } from 'node:path';
+export const SKILLS_MANIFEST_PATH = join('.moda', 'skills.yml');
+// Per-record `source` values. Harness-generated skills (pulled from the
+// tenant store) keep the legacy value 'moda'; skills materialized from the
+// CLI's bundled integration set use 'integration-bundled'. Pruning on a
+// release change is scoped to harness records only, and `skills sync`
+// excludes every managed path regardless of source.
+export const SKILL_SOURCE_HARNESS = 'moda';
+export const SKILL_SOURCE_INTEGRATION_BUNDLED = 'integration-bundled';
+export function readSkillsManifest(cwd) {
+    const manifestPath = join(cwd, SKILLS_MANIFEST_PATH);
+    if (!existsSync(manifestPath))
+        return null;
+    let text = '';
+    try {
+        text = readFileSync(manifestPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    return {
+        tenantId: readYamlScalar(text, 'tenant_id'),
+        generationRunId: readYamlScalar(text, 'generation_run_id'),
+        generationVersion: Number(readYamlScalar(text, 'generation_version') || 0),
+        releaseKey: readYamlScalar(text, 'release_key'),
+        statusFilter: readYamlScalar(text, 'status_filter'),
+        releasedAt: readYamlScalar(text, 'released_at'),
+        managedPaths: readManagedPaths(text),
+        records: readSkillRecords(text),
+    };
+}
+export function manifestHeaderFrom(manifest) {
+    return {
+        tenantId: manifest?.tenantId ?? '',
+        releaseKey: manifest?.releaseKey ?? '',
+        statusFilter: manifest?.statusFilter ?? '',
+        generationRunId: manifest?.generationRunId ?? '',
+        generationVersion: manifest?.generationVersion ?? 0,
+        releasedAt: manifest?.releasedAt ?? '',
+    };
+}
+export function writeSkillsManifest(cwd, header, records) {
+    const manifestPath = join(cwd, SKILLS_MANIFEST_PATH);
+    const managedPaths = [...new Set(records.flatMap((record) => record.paths))].sort();
+    const lines = [
+        'version: 1',
+        'source: moda',
+        `tenant_id: ${yamlQuote(header.tenantId)}`,
+        `release_key: ${yamlQuote(header.releaseKey)}`,
+        `status_filter: ${yamlQuote(header.statusFilter)}`,
+        `generation_run_id: ${yamlQuote(header.generationRunId)}`,
+        `generation_version: ${header.generationVersion}`,
+        `released_at: ${yamlQuote(header.releasedAt)}`,
+        `installed_at: ${yamlQuote(new Date().toISOString())}`,
+        'managed_paths:',
+        ...managedPaths.map((path) => `  - ${yamlQuote(path)}`),
+        'skills:',
+        ...records.flatMap((record) => [
+            `  - skill_id: ${yamlQuote(record.skillId)}`,
+            `    content_hash: ${yamlQuote(record.contentHash)}`,
+            `    source: ${yamlQuote(record.source)}`,
+            '    paths:',
+            ...record.paths.map((path) => `      - ${yamlQuote(path)}`),
+        ]),
+        '',
+    ];
+    mkdirSync(dirname(manifestPath), { recursive: true });
+    writeFileSync(manifestPath, lines.join('\n'));
+}
+/**
+ * Upsert a skill record into .moda/skills.yml, preserving the harness release
+ * header and all other records. Used by the bundled integration-skill
+ * installer so its materialized files become managed paths (excluded from
+ * `skills sync`, never pruned by harness release changes).
+ */
+export function upsertSkillManifestRecord(cwd, record) {
+    const manifest = readSkillsManifest(cwd);
+    const records = (manifest?.records ?? []).filter((existing) => !(existing.skillId === record.skillId && existing.source === record.source));
+    records.push(record);
+    writeSkillsManifest(cwd, manifestHeaderFrom(manifest), records);
+}
+export function pruneManagedSkillPaths(cwd, managedPaths, log) {
+    let pruned = 0;
+    for (const rawPath of [...new Set(managedPaths)]) {
+        const safePath = safeManagedRelativePath(rawPath);
+        if (!safePath)
+            continue;
+        const absolutePath = absoluteManagedPath(cwd, safePath);
+        if (!absolutePath || !existsSync(absolutePath))
+            continue;
+        try {
+            unlinkSync(absolutePath);
+            pruned++;
+            log(`  pruned ${safePath}`);
+            pruneEmptyClaudeSkillDir(cwd, safePath);
+        }
+        catch {
+            // Best-effort cleanup. The following write pass can still repair files
+            // that remain writable.
+        }
+    }
+    return pruned;
+}
+function pruneEmptyClaudeSkillDir(cwd, relativePath) {
+    if (!relativePath.startsWith('.claude/skills/') || !relativePath.endsWith('/SKILL.md'))
+        return;
+    const dir = dirname(join(cwd, relativePath));
+    try {
+        if (existsSync(dir) && readdirSync(dir).length === 0) {
+            rmdirSync(dir);
+        }
+    }
+    catch {
+        // Empty-dir pruning is only cosmetic.
+    }
+}
+function absoluteManagedPath(cwd, relativePath) {
+    const abs = resolve(cwd, relativePath);
+    const root = resolve(cwd);
+    const rel = relative(root, abs);
+    if (rel.startsWith('..') || isAbsolute(rel))
+        return null;
+    return abs;
+}
+function safeManagedRelativePath(rawPath) {
+    if (!rawPath || rawPath.includes('\0') || isAbsolute(rawPath))
+        return null;
+    const normalized = normalize(rawPath).replace(/\\/g, '/');
+    if (normalized.startsWith('../') || normalized === '..' || normalized.includes('/../'))
+        return null;
+    const isClaudeSkill = normalized.startsWith('.claude/skills/') && normalized.endsWith('/SKILL.md');
+    const isCursorRule = normalized.startsWith('.cursor/rules/') && normalized.endsWith('.mdc');
+    return isClaudeSkill || isCursorRule ? normalized : null;
+}
+function readYamlScalar(text, key) {
+    const match = text.match(new RegExp(`^${key}:\\s*(.*?)\\s*$`, 'm'));
+    return match ? parseYamlScalar(match[1]) : '';
+}
+/** Parse the `skills:` record list from the hand-rolled manifest YAML. */
+function readSkillRecords(text) {
+    const records = [];
+    let inSkills = false;
+    let current = null;
+    let inPaths = false;
+    for (const line of text.split(/\r?\n/)) {
+        if (line.trim() === 'skills:') {
+            inSkills = true;
+            continue;
+        }
+        if (!inSkills)
+            continue;
+        if (line.length > 0 && !line.startsWith(' '))
+            break;
+        const skillIdMatch = line.match(/^ {2}- skill_id:\s*(.*?)\s*$/);
+        if (skillIdMatch) {
+            if (current)
+                records.push(current);
+            current = {
+                skillId: parseYamlScalar(skillIdMatch[1]),
+                contentHash: '',
+                // Legacy manifests predate per-record sources; they were all pulls.
+                source: SKILL_SOURCE_HARNESS,
+                paths: [],
+            };
+            inPaths = false;
+            continue;
+        }
+        if (!current)
+            continue;
+        const hashMatch = line.match(/^ {4}content_hash:\s*(.*?)\s*$/);
+        if (hashMatch) {
+            current.contentHash = parseYamlScalar(hashMatch[1]);
+            continue;
+        }
+        const sourceMatch = line.match(/^ {4}source:\s*(.*?)\s*$/);
+        if (sourceMatch) {
+            current.source = parseYamlScalar(sourceMatch[1]) || SKILL_SOURCE_HARNESS;
+            continue;
+        }
+        if (/^ {4}paths:\s*$/.test(line)) {
+            inPaths = true;
+            continue;
+        }
+        const pathMatch = inPaths ? line.match(/^ {6}-\s*(.*?)\s*$/) : null;
+        if (pathMatch) {
+            const value = parseYamlScalar(pathMatch[1]);
+            if (value)
+                current.paths.push(value);
+        }
+    }
+    if (current)
+        records.push(current);
+    return records;
+}
+function readManagedPaths(text) {
+    const paths = [];
+    let inManagedPaths = false;
+    for (const line of text.split(/\r?\n/)) {
+        if (line.trim() === 'managed_paths:') {
+            inManagedPaths = true;
+            continue;
+        }
+        if (inManagedPaths && line.length > 0 && !line.startsWith(' '))
+            break;
+        if (!inManagedPaths)
+            continue;
+        const match = line.match(/^\s*-\s*(.*?)\s*$/);
+        if (match)
+            paths.push(parseYamlScalar(match[1]));
+    }
+    return paths.filter(Boolean);
+}
+function parseYamlScalar(raw) {
+    const value = raw.trim();
+    if (!value)
+        return '';
+    if (value.startsWith('"')) {
+        try {
+            return String(JSON.parse(value));
+        }
+        catch {
+            return value.replace(/^"|"$/g, '');
+        }
+    }
+    return value.replace(/^'|'$/g, '');
+}
+function yamlQuote(value) {
+    return JSON.stringify(value);
+}
+//# sourceMappingURL=skills-manifest.js.map

package/dist/skills.d.ts

@@ -1,4 +1,4 @@
-import type { ParsedArgs } from './cli.js';
+import { type CommandContext } from './command-context.js';
 import type { ProfileIOOptions } from './profiles.js';
 interface PullSummary {
     total: number;
@@ -46,6 +46,12 @@ export declare function runSkillSync(flags?: Record<string, string>, profileOpti
 /**
  * `moda skills <subcommand>` dispatcher.
  */
-export declare function runSkillsCommand(args: ParsedArgs): Promise<number>;
+type LegacySkillsArgs = {
+    command: string;
+    positional: string | undefined;
+    positionals: string[];
+    flags: Record<string, string>;
+};
+export declare function runSkillsCommand(input: CommandContext | LegacySkillsArgs): Promise<number>;
 export {};
 //# sourceMappingURL=skills.d.ts.map