@slats/claude-assets-sync 0.0.4 → 0.0.6

package/dist/core/sync.mjs

@@ -1,13 +1,47 @@
 import { logger } from '../utils/logger.mjs';
 import { toFlatFileName } from '../utils/nameTransform.mjs';
-import { findGitRoot, readLocalPackageJson, readPackageJson, parseGitHubRepo, buildVersionTag, buildAssetPath, getAssetTypes } from '../utils/package.mjs';
+import { findGitRoot, readLocalPackageJson, readPackageJson, parseGitHubRepo, buildAssetPath, getAssetTypes, buildVersionTag } from '../utils/package.mjs';
 import { packageNameToPrefix } from '../utils/packageName.mjs';
 import { getDestinationDir, getFlatDestinationDir } from '../utils/paths.mjs';
 import { cleanAssetDir, cleanFlatAssetFiles, writeAssetFile, writeFlatAssetFile, needsSync, writeSyncMeta, createSyncMeta } from './filesystem.mjs';
 import { fetchAssetFiles, downloadAssetFiles, RateLimitError } from './github.mjs';
+import { canUseLocalSource, fetchLocalAssetFiles, downloadLocalAssetFiles } from './localSource.mjs';
 import { readUnifiedSyncMeta, createEmptyUnifiedMeta, needsSyncUnified, updatePackageInMeta, writeUnifiedSyncMeta } from './syncMeta.mjs';
+import { SCHEMA_VERSIONS } from './constants.mjs';
 import { getAssetStructure } from './assetStructure.mjs';
 
+function groupEntriesIntoSkillUnits(entries, prefix) {
+    const dirGroups = new Map();
+    const singleFiles = [];
+    for (const entry of entries) {
+        const slashIndex = entry.name.indexOf('/');
+        if (slashIndex === -1) {
+            singleFiles.push({
+                name: entry.name,
+                isDirectory: false,
+                transformed: toFlatFileName(prefix, entry.name),
+            });
+        }
+        else {
+            const dirName = entry.name.substring(0, slashIndex);
+            const internalFile = entry.name.substring(slashIndex + 1);
+            if (!dirGroups.has(dirName)) {
+                dirGroups.set(dirName, []);
+            }
+            dirGroups.get(dirName).push(internalFile);
+        }
+    }
+    const dirSkillUnits = [];
+    for (const [dirName, internalFiles] of dirGroups.entries()) {
+        dirSkillUnits.push({
+            name: dirName,
+            isDirectory: true,
+            transformed: toFlatFileName(prefix, dirName),
+            internalFiles,
+        });
+    }
+    return [...singleFiles, ...dirSkillUnits];
+}
 const syncPackage = async (packageName, options, cwd = process.cwd(), exclusions, outputDir) => {
     logger.packageStart(packageName);
     try {
@@ -32,14 +66,6 @@ const syncPackage = async (packageName, options, cwd = process.cwd(), exclusions
                 reason: 'Package does not have claude.assetPath in package.json',
             };
         const repoInfo = parseGitHubRepo(packageInfo.repository);
-        if (!repoInfo) {
-            return {
-                packageName,
-                success: false,
-                skipped: true,
-                reason: 'Unable to parse GitHub repository URL',
-            };
-        }
         const useFlat = options.flat !== false;
         if (useFlat) {
             const prefix = packageNameToPrefix(packageName);
@@ -53,11 +79,32 @@ const syncPackage = async (packageName, options, cwd = process.cwd(), exclusions
                     reason: `Already synced at version ${packageInfo.version}`,
                 };
             }
-            const tag = options.ref ?? buildVersionTag(packageName, packageInfo.version);
             const assetPath = buildAssetPath(packageInfo.claude.assetPath);
-            logger.step('Fetching', `asset list from GitHub (ref: ${tag})`);
+            const useLocalSource = options.ref
+                ? { available: false }
+                : canUseLocalSource(packageName, packageInfo.version, assetPath, cwd);
             const assetTypes = getAssetTypes(packageInfo.claude);
-            const assetFiles = await fetchAssetFiles(repoInfo, assetPath, tag, assetTypes);
+            let assetFiles;
+            let isLocalSource;
+            if (useLocalSource.available && useLocalSource.docsPath) {
+                isLocalSource = true;
+                logger.step('Using', 'local docs from node_modules');
+                assetFiles = await fetchLocalAssetFiles(useLocalSource.docsPath, assetTypes);
+            }
+            else {
+                if (!repoInfo) {
+                    return {
+                        packageName,
+                        success: false,
+                        skipped: true,
+                        reason: `Package ${packageName} has no valid GitHub repository URL for remote fetch`,
+                    };
+                }
+                isLocalSource = false;
+                const tag = options.ref ?? buildVersionTag(packageName, packageInfo.version);
+                logger.step('Fetching', `asset list from GitHub (ref: ${tag})`);
+                assetFiles = await fetchAssetFiles(repoInfo, assetPath, tag, assetTypes);
+            }
             let totalFiles = 0;
             for (const assetType of assetTypes) {
                 totalFiles += (assetFiles[assetType] || []).length;
@@ -88,45 +135,41 @@ const syncPackage = async (packageName, options, cwd = process.cwd(), exclusions
                     continue;
                 const structure = getAssetStructure(assetType, packageInfo.claude);
                 if (structure === 'nested') {
-                    fileMappings[assetType] = filteredEntries.map((e) => e.name);
+                    fileMappings[assetType] = filteredEntries.map((e) => ({
+                        name: e.name,
+                        isDirectory: false,
+                    }));
                 }
                 else {
-                    fileMappings[assetType] = filteredEntries.map((entry) => ({
-                        original: entry.name,
-                        transformed: toFlatFileName(prefix, entry.name),
-                    }));
+                    fileMappings[assetType] = groupEntriesIntoSkillUnits(filteredEntries, prefix);
                 }
             }
             if (options.dryRun) {
                 for (const assetType of assetTypes) {
-                    const mappings = fileMappings[assetType];
-                    if (!mappings || mappings.length === 0)
+                    const units = fileMappings[assetType];
+                    if (!units || units.length === 0)
                         continue;
                     const structure = getAssetStructure(assetType, packageInfo.claude);
                     if (structure === 'nested') {
                         logger.step(`Would sync ${assetType} to`, getDestinationDir(destDir, packageName, assetType));
-                        mappings.forEach((fileName) => {
-                            logger.file('create', fileName);
+                        units.forEach((unit) => {
+                            logger.file('create', unit.name);
                         });
                     }
                     else {
                         logger.step(`Would sync ${assetType} to`, getFlatDestinationDir(destDir, assetType));
-                        mappings.forEach((mapping) => {
-                            logger.file('create', mapping.transformed);
+                        units.forEach((unit) => {
+                            const displayName = unit.transformed ?? unit.name;
+                            logger.file('create', displayName);
                         });
                     }
                 }
                 const syncedFiles = {};
                 for (const assetType of assetTypes) {
-                    const mappings = fileMappings[assetType];
-                    if (!mappings || mappings.length === 0)
+                    const units = fileMappings[assetType];
+                    if (!units || units.length === 0)
                         continue;
-                    if (typeof mappings[0] === 'string') {
-                        syncedFiles[assetType] = mappings;
-                    }
-                    else {
-                        syncedFiles[assetType] = mappings.map((m) => m.transformed);
-                    }
+                    syncedFiles[assetType] = units.map((u) => u.transformed ?? u.name);
                 }
                 return {
                     packageName,
@@ -158,7 +201,14 @@ const syncPackage = async (packageName, options, cwd = process.cwd(), exclusions
                     continue;
                 const structure = getAssetStructure(assetType, packageInfo.claude);
                 logger.step('Downloading', assetType);
-                const downloadedFiles = await downloadAssetFiles(repoInfo, assetPath, assetType, filteredEntries, tag);
+                let downloadedFiles;
+                if (isLocalSource && useLocalSource.docsPath) {
+                    downloadedFiles = await downloadLocalAssetFiles(useLocalSource.docsPath, assetType, filteredEntries);
+                }
+                else {
+                    const tag = options.ref ?? buildVersionTag(packageName, packageInfo.version);
+                    downloadedFiles = await downloadAssetFiles(repoInfo, assetPath, assetType, filteredEntries, tag);
+                }
                 if (structure === 'nested') {
                     for (const [fileName, content] of downloadedFiles) {
                         writeAssetFile(destDir, packageName, assetType, fileName, content);
@@ -166,10 +216,8 @@ const syncPackage = async (packageName, options, cwd = process.cwd(), exclusions
                     }
                 }
                 else {
-                    const mappings = fileMappings[assetType];
                     for (const [fileName, content] of downloadedFiles) {
-                        const mapping = mappings.find((m) => m.original === fileName);
-                        const flatName = mapping?.transformed ?? toFlatFileName(prefix, fileName);
+                        const flatName = toFlatFileName(prefix, fileName);
                         writeFlatAssetFile(destDir, assetType, flatName, content);
                         logger.file('create', flatName);
                     }
@@ -185,18 +233,14 @@ const syncPackage = async (packageName, options, cwd = process.cwd(), exclusions
                     ? exclusions
                     : undefined,
             });
+            updatedMeta.skillUnitFormat = SCHEMA_VERSIONS.SKILL_UNIT_FORMAT;
             writeUnifiedSyncMeta(destDir, updatedMeta);
             const syncedFiles = {};
             for (const assetType of assetTypes) {
-                const mappings = fileMappings[assetType];
-                if (!mappings || mappings.length === 0)
+                const units = fileMappings[assetType];
+                if (!units || units.length === 0)
                     continue;
-                if (typeof mappings[0] === 'string') {
-                    syncedFiles[assetType] = mappings;
-                }
-                else {
-                    syncedFiles[assetType] = mappings.map((m) => m.transformed);
-                }
+                syncedFiles[assetType] = units.map((u) => u.transformed ?? u.name);
             }
             return {
                 packageName,
@@ -206,11 +250,32 @@ const syncPackage = async (packageName, options, cwd = process.cwd(), exclusions
             };
         }
         else {
-            const tag = options.ref ?? buildVersionTag(packageName, packageInfo.version);
             const assetPath = buildAssetPath(packageInfo.claude.assetPath);
-            logger.step('Fetching', `asset list from GitHub (ref: ${tag})`);
+            const useLocalSource = options.ref
+                ? { available: false }
+                : canUseLocalSource(packageName, packageInfo.version, assetPath, cwd);
             const assetTypes = getAssetTypes(packageInfo.claude);
-            const assetFiles = await fetchAssetFiles(repoInfo, assetPath, tag, assetTypes);
+            let assetFiles;
+            let isLocalSource;
+            if (useLocalSource.available && useLocalSource.docsPath) {
+                isLocalSource = true;
+                logger.step('Using', 'local docs from node_modules');
+                assetFiles = await fetchLocalAssetFiles(useLocalSource.docsPath, assetTypes);
+            }
+            else {
+                if (!repoInfo) {
+                    return {
+                        packageName,
+                        success: false,
+                        skipped: true,
+                        reason: `Package ${packageName} has no valid GitHub repository URL for remote fetch`,
+                    };
+                }
+                isLocalSource = false;
+                const tag = options.ref ?? buildVersionTag(packageName, packageInfo.version);
+                logger.step('Fetching', `asset list from GitHub (ref: ${tag})`);
+                assetFiles = await fetchAssetFiles(repoInfo, assetPath, tag, assetTypes);
+            }
             let totalFiles = 0;
             for (const assetType of assetTypes) {
                 totalFiles += (assetFiles[assetType] || []).length;
@@ -274,7 +339,14 @@ const syncPackage = async (packageName, options, cwd = process.cwd(), exclusions
                 if (filteredEntries.length === 0)
                     continue;
                 logger.step('Downloading', assetType);
-                const downloadedFiles = await downloadAssetFiles(repoInfo, assetPath, assetType, filteredEntries, tag);
+                let downloadedFiles;
+                if (isLocalSource && useLocalSource.docsPath) {
+                    downloadedFiles = await downloadLocalAssetFiles(useLocalSource.docsPath, assetType, filteredEntries);
+                }
+                else {
+                    const tag = options.ref ?? buildVersionTag(packageName, packageInfo.version);
+                    downloadedFiles = await downloadAssetFiles(repoInfo, assetPath, assetType, filteredEntries, tag);
+                }
                 cleanAssetDir(destDir, packageName, assetType);
                 syncedFiles[assetType] = [];
                 for (const [fileName, content] of downloadedFiles) {

package/dist/core/syncMeta.cjs

@@ -9,7 +9,11 @@ const UNIFIED_META_PATH = constants.META_FILES.UNIFIED_SYNC_META;
 const SCHEMA_VERSION = constants.SCHEMA_VERSIONS.UNIFIED_SYNC_META;
 function readUnifiedSyncMeta(cwd) {
     const metaPath = path.join(cwd, UNIFIED_META_PATH);
-    return io.readJsonFile(metaPath);
+    const meta = io.readJsonFile(metaPath);
+    if (meta && needsSkillUnitMigration(meta)) {
+        return migrateToSkillUnitSchema(meta);
+    }
+    return meta;
 }
 function writeUnifiedSyncMeta(cwd, meta) {
     const metaPath = path.join(cwd, UNIFIED_META_PATH);
@@ -55,16 +59,14 @@ function createEmptyUnifiedMeta() {
         packages: {},
     };
 }
-function removeFileFromPackage(meta, prefix, assetType, fileName) {
+function removeSkillUnitFromPackage(meta, prefix, assetType, skillName) {
     const pkgInfo = meta.packages[prefix];
     if (!pkgInfo) {
         throw new Error(`Package ${prefix} not found in metadata`);
     }
-    const existingFiles = pkgInfo.files[assetType] || [];
-    const updatedFiles = existingFiles.filter((f) => typeof f === 'string'
-        ? f !== fileName
-        : f.original !== fileName && f.transformed !== fileName);
-    if (existingFiles.length === updatedFiles.length) {
+    const existingUnits = (pkgInfo.files[assetType] || []);
+    const updatedUnits = existingUnits.filter((u) => u.name !== skillName);
+    if (existingUnits.length === updatedUnits.length) {
         return meta;
     }
     return {
@@ -76,18 +78,160 @@ function removeFileFromPackage(meta, prefix, assetType, fileName) {
                 ...pkgInfo,
                 files: {
                     ...pkgInfo.files,
-                    [assetType]: updatedFiles,
+                    [assetType]: updatedUnits,
+                },
+            },
+        },
+    };
+}
+function updatePackageVersion(meta, prefix, newVersion) {
+    const pkgInfo = meta.packages[prefix];
+    if (!pkgInfo) {
+        throw new Error(`Package ${prefix} not found in metadata`);
+    }
+    return {
+        ...meta,
+        syncedAt: new Date().toISOString(),
+        packages: {
+            ...meta.packages,
+            [prefix]: {
+                ...pkgInfo,
+                version: newVersion,
+            },
+        },
+    };
+}
+function updatePackageFilesystemMeta(meta, prefix, assetType, updatedUnits) {
+    const pkgInfo = meta.packages[prefix];
+    if (!pkgInfo) {
+        throw new Error(`Package ${prefix} not found in metadata`);
+    }
+    return {
+        ...meta,
+        syncedAt: new Date().toISOString(),
+        skillUnitFormat: constants.SCHEMA_VERSIONS.SKILL_UNIT_FORMAT,
+        packages: {
+            ...meta.packages,
+            [prefix]: {
+                ...pkgInfo,
+                files: {
+                    ...pkgInfo.files,
+                    [assetType]: updatedUnits,
                 },
             },
         },
     };
 }
+function needsSkillUnitMigration(meta) {
+    if (meta.skillUnitFormat === constants.SCHEMA_VERSIONS.SKILL_UNIT_FORMAT) {
+        return false;
+    }
+    for (const pkgInfo of Object.values(meta.packages)) {
+        for (const rawFiles of Object.values(pkgInfo.files)) {
+            const files = rawFiles;
+            if (!Array.isArray(files) || files.length === 0) {
+                continue;
+            }
+            const first = files[0];
+            if (typeof first === 'string') {
+                return true;
+            }
+            if (typeof first === 'object' &&
+                first !== null &&
+                'original' in first &&
+                'transformed' in first &&
+                !('isDirectory' in first)) {
+                return true;
+            }
+            if (typeof first === 'object' && first !== null && 'isDirectory' in first) {
+                return false;
+            }
+        }
+    }
+    return false;
+}
+function migrateToSkillUnitSchema(meta) {
+    const migratedPackages = {};
+    for (const [prefix, pkgInfo] of Object.entries(meta.packages)) {
+        const migratedFiles = {};
+        for (const [assetType, rawFiles] of Object.entries(pkgInfo.files)) {
+            const files = rawFiles;
+            if (!Array.isArray(files) || files.length === 0) {
+                migratedFiles[assetType] = [];
+                continue;
+            }
+            const first = files[0];
+            if (typeof first === 'string') {
+                migratedFiles[assetType] = files.map((name) => ({
+                    name,
+                    isDirectory: false,
+                }));
+            }
+            else if (typeof first === 'object' &&
+                first !== null &&
+                'original' in first &&
+                !('isDirectory' in first)) {
+                const fileMappings = files;
+                const groupedByDir = new Map();
+                const singleFiles = [];
+                for (const mapping of fileMappings) {
+                    const slashIndex = mapping.original.indexOf('/');
+                    if (slashIndex === -1) {
+                        singleFiles.push({
+                            name: mapping.original,
+                            isDirectory: false,
+                            transformed: mapping.transformed,
+                        });
+                    }
+                    else {
+                        const dirName = mapping.original.substring(0, slashIndex);
+                        const internalFile = mapping.original.substring(slashIndex + 1);
+                        const transformedSlashIndex = mapping.transformed.indexOf('/');
+                        const transformedDir = transformedSlashIndex !== -1
+                            ? mapping.transformed.substring(0, transformedSlashIndex)
+                            : mapping.transformed;
+                        if (!groupedByDir.has(dirName)) {
+                            groupedByDir.set(dirName, { transformed: transformedDir, internalFiles: [] });
+                        }
+                        groupedByDir.get(dirName).internalFiles.push(internalFile);
+                    }
+                }
+                const dirSkillUnits = [];
+                for (const [dirName, data] of groupedByDir.entries()) {
+                    dirSkillUnits.push({
+                        name: dirName,
+                        isDirectory: true,
+                        transformed: data.transformed,
+                        internalFiles: data.internalFiles,
+                    });
+                }
+                migratedFiles[assetType] = [...singleFiles, ...dirSkillUnits];
+            }
+            else {
+                migratedFiles[assetType] = files;
+            }
+        }
+        migratedPackages[prefix] = {
+            ...pkgInfo,
+            files: migratedFiles,
+        };
+    }
+    return {
+        ...meta,
+        skillUnitFormat: constants.SCHEMA_VERSIONS.SKILL_UNIT_FORMAT,
+        packages: migratedPackages,
+    };
+}
 
 exports.SCHEMA_VERSION = SCHEMA_VERSION;
 exports.createEmptyUnifiedMeta = createEmptyUnifiedMeta;
+exports.migrateToSkillUnitSchema = migrateToSkillUnitSchema;
+exports.needsSkillUnitMigration = needsSkillUnitMigration;
 exports.needsSyncUnified = needsSyncUnified;
 exports.readUnifiedSyncMeta = readUnifiedSyncMeta;
-exports.removeFileFromPackage = removeFileFromPackage;
 exports.removePackageFromMeta = removePackageFromMeta;
+exports.removeSkillUnitFromPackage = removeSkillUnitFromPackage;
+exports.updatePackageFilesystemMeta = updatePackageFilesystemMeta;
 exports.updatePackageInMeta = updatePackageInMeta;
+exports.updatePackageVersion = updatePackageVersion;
 exports.writeUnifiedSyncMeta = writeUnifiedSyncMeta;

package/dist/core/syncMeta.d.ts

@@ -1,8 +1,8 @@
-import type { PackageSyncInfo, UnifiedSyncMeta } from '../utils/types.js';
+import type { PackageSyncInfo, SkillUnit, UnifiedSyncMeta } from '../utils/types.js';
 /**
  * Schema version for the unified metadata format
  */
-export declare const SCHEMA_VERSION: "0.0.4";
+export declare const SCHEMA_VERSION: "0.0.6";
 /**
  * Read unified sync metadata from .claude/.sync-meta.json
  *
@@ -50,22 +50,26 @@ export declare function needsSyncUnified(meta: UnifiedSyncMeta | null, prefix: s
  */
 export declare function createEmptyUnifiedMeta(): UnifiedSyncMeta;
 /**
- * Add a file to a package's asset type in unified metadata
- *
- * @param meta - Current unified metadata
- * @param prefix - Package prefix (e.g., 'canard-schema-form')
- * @param assetType - Asset type (e.g., 'commands', 'skills')
- * @param fileName - File name to add
- * @returns Updated metadata object
+ * Add a skill unit to a package's asset type in unified metadata
  */
-export declare function addFileToPackage(meta: UnifiedSyncMeta, prefix: string, assetType: string, fileName: string): UnifiedSyncMeta;
+export declare function addSkillUnitToPackage(meta: UnifiedSyncMeta, prefix: string, assetType: string, unit: SkillUnit): UnifiedSyncMeta;
 /**
- * Remove a file from a package's asset type in unified metadata
- *
- * @param meta - Current unified metadata
- * @param prefix - Package prefix (e.g., 'canard-schema-form')
- * @param assetType - Asset type (e.g., 'commands', 'skills')
- * @param fileName - File name to remove
- * @returns Updated metadata object
+ * Remove a skill unit from a package's asset type in unified metadata
+ */
+export declare function removeSkillUnitFromPackage(meta: UnifiedSyncMeta, prefix: string, assetType: string, skillName: string): UnifiedSyncMeta;
+/**
+ * Update package version in unified metadata
+ */
+export declare function updatePackageVersion(meta: UnifiedSyncMeta, prefix: string, newVersion: string): UnifiedSyncMeta;
+/**
+ * Update filesystem metadata for a package's asset type
+ */
+export declare function updatePackageFilesystemMeta(meta: UnifiedSyncMeta, prefix: string, assetType: string, updatedUnits: SkillUnit[]): UnifiedSyncMeta;
+/**
+ * Check if unified metadata needs migration to SkillUnit format
+ */
+export declare function needsSkillUnitMigration(meta: UnifiedSyncMeta): boolean;
+/**
+ * Migrate unified metadata from old format to SkillUnit format (in-memory only)
  */
-export declare function removeFileFromPackage(meta: UnifiedSyncMeta, prefix: string, assetType: string, fileName: string): UnifiedSyncMeta;
+export declare function migrateToSkillUnitSchema(meta: UnifiedSyncMeta): UnifiedSyncMeta;