@slats/claude-assets-sync 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vincent K. Kelvin
+
+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.

package/README.md

@@ -0,0 +1,144 @@
+# @slats/claude-assets-sync
+
+CLI tool to sync Claude commands and skills from npm packages to your project's `.claude/` directory.
+
+## Overview
+
+This tool allows npm package authors to distribute Claude Code commands and skills alongside their packages. When users install these packages, they can sync the Claude assets to their local `.claude/` directory for immediate use with Claude Code.
+
+## Installation
+
+```bash
+# Using npx (recommended for one-time use)
+npx @slats/claude-assets-sync -p @canard/schema-form
+
+# Or install globally
+npm install -g @slats/claude-assets-sync
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Sync a single package
+npx @slats/claude-assets-sync -p @canard/schema-form
+
+# Sync multiple packages
+npx @slats/claude-assets-sync -p @canard/schema-form -p @lerx/promise-modal
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-p, --package <name>` | Package name to sync (can be specified multiple times) |
+| `-f, --force` | Force sync even if version matches |
+| `--dry-run` | Preview changes without writing files |
+| `--help` | Show help |
+| `--version` | Show version |
+
+### Examples
+
+```bash
+# Preview what would be synced
+npx @slats/claude-assets-sync -p @canard/schema-form --dry-run
+
+# Force sync (ignore version check)
+npx @slats/claude-assets-sync -p @canard/schema-form --force
+
+# Sync with GitHub token (for higher rate limits)
+GITHUB_TOKEN=ghp_xxx npx @slats/claude-assets-sync -p @canard/schema-form
+```
+
+## For Package Authors
+
+To make your package compatible with `claude-assets-sync`, add a `claude` field to your `package.json`:
+
+```json
+{
+  "name": "@your-scope/your-package",
+  "version": "1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-org/your-repo.git",
+    "directory": "packages/your-package"
+  },
+  "claude": {
+    "assetPath": "docs/claude"
+  }
+}
+```
+
+### Directory Structure
+
+Your package should have the following structure:
+
+```
+your-package/
+├── docs/
+│   └── claude/
+│       ├── commands/
+│       │   └── your-command.md
+│       └── skills/
+│           └── your-skill.md
+└── package.json
+```
+
+### File Format
+
+- Commands and skills should be Markdown files (`.md`)
+- Files are synced directly without modification
+- Use the standard Claude Code command/skill format
+
+## Destination Structure
+
+Synced files are organized in your project's `.claude/` directory:
+
+```
+your-project/
+└── .claude/
+    ├── commands/
+    │   └── @your-scope/
+    │       └── your-package/
+    │           ├── your-command.md
+    │           └── .sync-meta.json
+    └── skills/
+        └── @your-scope/
+            └── your-package/
+                ├── your-skill.md
+                └── .sync-meta.json
+```
+
+## Version Management
+
+The tool creates `.sync-meta.json` files to track synced versions:
+
+```json
+{
+  "version": "1.0.0",
+  "syncedAt": "2025-02-01T12:00:00.000Z",
+  "files": ["your-command.md"]
+}
+```
+
+- Sync is skipped if the local version matches the package version
+- Use `--force` to override version checking
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_TOKEN` | GitHub personal access token for higher API rate limits |
+| `VERBOSE` | Enable debug logging |
+
+## Rate Limits
+
+- **Without token**: 60 requests/hour (GitHub API limit)
+- **With token**: 5,000 requests/hour
+
+For most use cases, the unauthenticated limit is sufficient. If syncing many packages, set `GITHUB_TOKEN`.
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) for details.

package/dist/@aileron/declare/function.d.ts

@@ -0,0 +1,16 @@
+export interface Fn<Params extends Array<any> = [], Return = void> {
+  (...props: Params): Return;
+}
+
+export interface AsyncFn<Params extends Array<any> = [], Return = void> {
+  (...props: Params): Promise<Return>;
+}
+
+export type SetStateFn<S = unknown> = (
+  value: S | ((prevState: S) => S),
+) => void;
+
+export type Parameter<
+  F extends Fn<[any]> | SetStateFn<any> | undefined,
+  I extends number = 0,
+> = Parameters<NonNullable<F>>[I];

package/dist/@aileron/declare/index.d.ts

@@ -0,0 +1,4 @@
+export * from './function';
+export * from './object';
+export * from './utility';
+export * from './unit';

package/dist/@aileron/declare/object.d.ts

@@ -0,0 +1,11 @@
+export type Dictionary<T = any> = Record<string, T>;
+
+export type StringDictionary = Dictionary<string>;
+
+export type DeepRequired<T> = {
+  [P in keyof T]-?: NonNullable<T[P]> extends object
+    ? NonNullable<T[P]> extends any[]
+      ? DeepRequired<NonNullable<T[P]>[number]>[]
+      : DeepRequired<NonNullable<T[P]>>
+    : T[P];
+};

package/dist/@aileron/declare/unit.d.ts

@@ -0,0 +1,19 @@
+export type DomSize =
+  | number
+  | `${number}%`
+  | `${number}px`
+  | `${number}rem`
+  | `${number}em`
+  | `${number}vh`
+  | `${number}vw`
+  | `calc(${string})`;
+
+export type Color =
+  | `#${string}`
+  | `rgb(${number}, ${number}, ${number})`
+  | `rgba(${number}, ${number}, ${number}, ${number})`
+  | `var(--${string})`;
+
+export type Time = `${number}ms` | `${number}s`;
+
+export type Duration = `${number}ms`;

package/dist/@aileron/declare/utility.d.ts

@@ -0,0 +1,45 @@
+export type Nullish = null | undefined;
+
+export type Nullable<T> = T | null;
+
+export type IsNullable<T> = [null] extends [T] ? true : false;
+
+export type Optional<T> = T | undefined;
+
+/** Extract keys K from T and make them required */
+export type PickRequired<T, K extends keyof T> = Required<Pick<T, K>>;
+
+/** Extract keys K from T and make them partial */
+export type PickPartial<T, K extends keyof T> = Partial<Pick<T, K>>;
+
+/** Omit keys K from T and make the rest required */
+export type OmitRequired<T, K extends keyof T> = Required<Omit<T, K>>;
+
+/** Omit keys K from T and make the rest partial */
+export type OmitPartial<T, K extends keyof T> = Partial<Omit<T, K>>;
+
+/** Make keys K required and the rest partial in T */
+export type PickAndPartial<T, K extends keyof T> = PickRequired<T, K> &
+  OmitPartial<T, K>;
+
+/** Make keys K required in T while keeping the rest unchanged */
+export type RequiredBy<T, K extends keyof T> = PickRequired<T, K> & T;
+
+/** Make keys K partial in T while keeping the rest unchanged */
+export type PartialBy<T, K extends keyof T> = PickPartial<T, K> & Omit<T, K>;
+
+export type Roll<T> = { [K in keyof T]: T[K] };
+
+export type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;
+
+export type ExpandRecursively<T> = T extends object
+  ? T extends infer O
+    ? { [K in keyof O]: ExpandRecursively<O[K]> }
+    : never
+  : T;
+
+export type WithKey<T> = T & { key: string };
+
+export type ElementOf<T extends any[]> = T[number];
+
+export type Params<T extends Array<string>> = Record<T[number], string>;

package/dist/cli/index.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+var commander = require('commander');
+var sync = require('../core/sync.cjs');
+var logger = require('../utils/logger.cjs');
+
+const runSync = async (options) => {
+    if (options.package.length === 0) {
+        logger.logger.error('No packages specified. Use -p <package> to specify packages.');
+        logger.logger.info('Example: claude-assets-sync -p @canard/schema-form');
+        process.exit(1);
+    }
+    if (options.dryRun)
+        logger.logger.dryRunNotice();
+    if (options.local)
+        logger.logger.info('[LOCAL MODE] Reading packages from workspace instead of node_modules\n');
+    const results = await sync.syncPackages(options.package, {
+        force: options.force,
+        dryRun: options.dryRun,
+        local: options.local,
+        ref: options.ref,
+    });
+    const hasFailures = results.some((r) => !r.success && !r.skipped);
+    if (hasFailures)
+        process.exit(1);
+};
+const createProgram = () => {
+    const program = new commander.Command();
+    program
+        .name('claude-assets-sync')
+        .description('Sync Claude commands and skills from npm packages to your project')
+        .version('0.1.0')
+        .option('-p, --package <name>', 'Package name to sync (can be specified multiple times)', (value, previous) => [...previous, value], [])
+        .option('-f, --force', 'Force sync even if version matches', false)
+        .option('--dry-run', 'Preview changes without writing files', false)
+        .option('-l, --local', 'Read packages from local workspace instead of node_modules', false)
+        .option('-r, --ref <ref>', 'Git ref (branch, tag, or commit) to fetch from (overrides version tag)')
+        .action(async (opts) => {
+        const options = {
+            package: opts.package,
+            force: opts.force,
+            dryRun: opts.dryRun,
+            local: opts.local,
+            ref: opts.ref,
+        };
+        await runSync(options);
+    });
+    return program;
+};
+const run = async () => {
+    const program = createProgram();
+    await program.parseAsync(process.argv);
+};
+
+exports.createProgram = createProgram;
+exports.run = run;

package/dist/cli/index.d.ts

@@ -0,0 +1,9 @@
+import { Command } from 'commander';
+/**
+ * Create and configure the CLI program
+ */
+export declare const createProgram: () => Command;
+/**
+ * Run the CLI
+ */
+export declare const run: () => Promise<void>;

package/dist/cli/index.mjs

@@ -0,0 +1,53 @@
+import { Command } from 'commander';
+import { syncPackages } from '../core/sync.mjs';
+import { logger } from '../utils/logger.mjs';
+
+const runSync = async (options) => {
+    if (options.package.length === 0) {
+        logger.error('No packages specified. Use -p <package> to specify packages.');
+        logger.info('Example: claude-assets-sync -p @canard/schema-form');
+        process.exit(1);
+    }
+    if (options.dryRun)
+        logger.dryRunNotice();
+    if (options.local)
+        logger.info('[LOCAL MODE] Reading packages from workspace instead of node_modules\n');
+    const results = await syncPackages(options.package, {
+        force: options.force,
+        dryRun: options.dryRun,
+        local: options.local,
+        ref: options.ref,
+    });
+    const hasFailures = results.some((r) => !r.success && !r.skipped);
+    if (hasFailures)
+        process.exit(1);
+};
+const createProgram = () => {
+    const program = new Command();
+    program
+        .name('claude-assets-sync')
+        .description('Sync Claude commands and skills from npm packages to your project')
+        .version('0.1.0')
+        .option('-p, --package <name>', 'Package name to sync (can be specified multiple times)', (value, previous) => [...previous, value], [])
+        .option('-f, --force', 'Force sync even if version matches', false)
+        .option('--dry-run', 'Preview changes without writing files', false)
+        .option('-l, --local', 'Read packages from local workspace instead of node_modules', false)
+        .option('-r, --ref <ref>', 'Git ref (branch, tag, or commit) to fetch from (overrides version tag)')
+        .action(async (opts) => {
+        const options = {
+            package: opts.package,
+            force: opts.force,
+            dryRun: opts.dryRun,
+            local: opts.local,
+            ref: opts.ref,
+        };
+        await runSync(options);
+    });
+    return program;
+};
+const run = async () => {
+    const program = createProgram();
+    await program.parseAsync(process.argv);
+};
+
+export { createProgram, run };

package/dist/core/filesystem.cjs

@@ -0,0 +1,81 @@
+'use strict';
+
+var node_fs = require('node:fs');
+var node_path = require('node:path');
+
+const parsePackageName = (packageName) => {
+    if (packageName.startsWith('@')) {
+        const [scope, name] = packageName.split('/');
+        return [scope, name];
+    }
+    return ['', packageName];
+};
+const getDestinationDir = (cwd, packageName, assetType) => {
+    const [scope, name] = parsePackageName(packageName);
+    if (scope)
+        return node_path.join(cwd, '.claude', assetType, scope, name);
+    return node_path.join(cwd, '.claude', assetType, name);
+};
+const ensureDir = (dirPath) => {
+    if (!node_fs.existsSync(dirPath)) {
+        node_fs.mkdirSync(dirPath, { recursive: true });
+    }
+};
+const writeFile = (filePath, content) => {
+    ensureDir(node_path.dirname(filePath));
+    node_fs.writeFileSync(filePath, content, 'utf-8');
+};
+const readSyncMeta = (cwd, packageName, assetType) => {
+    try {
+        const destDir = getDestinationDir(cwd, packageName, assetType);
+        const metaPath = node_path.join(destDir, '.sync-meta.json');
+        const content = node_fs.readFileSync(metaPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+};
+const writeSyncMeta = (cwd, packageName, assetType, meta) => {
+    const destDir = getDestinationDir(cwd, packageName, assetType);
+    const metaPath = node_path.join(destDir, '.sync-meta.json');
+    writeFile(metaPath, JSON.stringify(meta, null, 2));
+};
+const writeAssetFile = (cwd, packageName, assetType, fileName, content) => {
+    const destDir = getDestinationDir(cwd, packageName, assetType);
+    const filePath = node_path.join(destDir, fileName);
+    writeFile(filePath, content);
+};
+const cleanAssetDir = (cwd, packageName, assetType) => {
+    const destDir = getDestinationDir(cwd, packageName, assetType);
+    if (node_fs.existsSync(destDir)) {
+        node_fs.rmSync(destDir, { recursive: true, force: true });
+    }
+};
+const needsSync = (cwd, packageName, version) => {
+    const commandsMeta = readSyncMeta(cwd, packageName, 'commands');
+    const skillsMeta = readSyncMeta(cwd, packageName, 'skills');
+    if (!commandsMeta && !skillsMeta)
+        return true;
+    if (commandsMeta && commandsMeta.version !== version)
+        return true;
+    if (skillsMeta && skillsMeta.version !== version)
+        return true;
+    return false;
+};
+const createSyncMeta = (version, files) => ({
+    version,
+    syncedAt: new Date().toISOString(),
+    files,
+});
+
+exports.cleanAssetDir = cleanAssetDir;
+exports.createSyncMeta = createSyncMeta;
+exports.ensureDir = ensureDir;
+exports.getDestinationDir = getDestinationDir;
+exports.needsSync = needsSync;
+exports.parsePackageName = parsePackageName;
+exports.readSyncMeta = readSyncMeta;
+exports.writeAssetFile = writeAssetFile;
+exports.writeFile = writeFile;
+exports.writeSyncMeta = writeSyncMeta;

package/dist/core/filesystem.d.ts

@@ -0,0 +1,73 @@
+import type { AssetType, SyncMeta } from '../utils/types';
+/**
+ * Parse scoped package name into scope and name
+ * @param packageName - Package name (e.g., "@canard/schema-form")
+ * @returns [scope, name] tuple (e.g., ["@canard", "schema-form"])
+ */
+export declare const parsePackageName: (packageName: string) => [string, string];
+/**
+ * Get the destination directory for synced assets
+ * @param cwd - Current working directory
+ * @param packageName - Package name
+ * @param assetType - Asset type (commands or skills)
+ * @returns Full path to destination directory
+ */
+export declare const getDestinationDir: (cwd: string, packageName: string, assetType: AssetType) => string;
+/**
+ * Ensure directory exists (creates recursively if needed)
+ * @param dirPath - Directory path
+ */
+export declare const ensureDir: (dirPath: string) => void;
+/**
+ * Write file with directory creation
+ * @param filePath - Full file path
+ * @param content - File content
+ */
+export declare const writeFile: (filePath: string, content: string) => void;
+/**
+ * Read sync metadata file
+ * @param cwd - Current working directory
+ * @param packageName - Package name
+ * @param assetType - Asset type
+ * @returns SyncMeta or null if not found
+ */
+export declare const readSyncMeta: (cwd: string, packageName: string, assetType: AssetType) => SyncMeta | null;
+/**
+ * Write sync metadata file
+ * @param cwd - Current working directory
+ * @param packageName - Package name
+ * @param assetType - Asset type
+ * @param meta - Sync metadata
+ */
+export declare const writeSyncMeta: (cwd: string, packageName: string, assetType: AssetType, meta: SyncMeta) => void;
+/**
+ * Write asset file to destination
+ * @param cwd - Current working directory
+ * @param packageName - Package name
+ * @param assetType - Asset type
+ * @param fileName - File name
+ * @param content - File content
+ */
+export declare const writeAssetFile: (cwd: string, packageName: string, assetType: AssetType, fileName: string, content: string) => void;
+/**
+ * Clean existing synced files for a package
+ * @param cwd - Current working directory
+ * @param packageName - Package name
+ * @param assetType - Asset type
+ */
+export declare const cleanAssetDir: (cwd: string, packageName: string, assetType: AssetType) => void;
+/**
+ * Check if package assets need sync (version mismatch)
+ * @param cwd - Current working directory
+ * @param packageName - Package name
+ * @param version - Current package version
+ * @returns true if sync is needed
+ */
+export declare const needsSync: (cwd: string, packageName: string, version: string) => boolean;
+/**
+ * Create SyncMeta object for current sync operation
+ * @param version - Package version
+ * @param files - List of synced file names
+ * @returns SyncMeta object
+ */
+export declare const createSyncMeta: (version: string, files: string[]) => SyncMeta;

package/dist/core/filesystem.mjs

@@ -0,0 +1,70 @@
+import { existsSync, rmSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+const parsePackageName = (packageName) => {
+    if (packageName.startsWith('@')) {
+        const [scope, name] = packageName.split('/');
+        return [scope, name];
+    }
+    return ['', packageName];
+};
+const getDestinationDir = (cwd, packageName, assetType) => {
+    const [scope, name] = parsePackageName(packageName);
+    if (scope)
+        return join(cwd, '.claude', assetType, scope, name);
+    return join(cwd, '.claude', assetType, name);
+};
+const ensureDir = (dirPath) => {
+    if (!existsSync(dirPath)) {
+        mkdirSync(dirPath, { recursive: true });
+    }
+};
+const writeFile = (filePath, content) => {
+    ensureDir(dirname(filePath));
+    writeFileSync(filePath, content, 'utf-8');
+};
+const readSyncMeta = (cwd, packageName, assetType) => {
+    try {
+        const destDir = getDestinationDir(cwd, packageName, assetType);
+        const metaPath = join(destDir, '.sync-meta.json');
+        const content = readFileSync(metaPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+};
+const writeSyncMeta = (cwd, packageName, assetType, meta) => {
+    const destDir = getDestinationDir(cwd, packageName, assetType);
+    const metaPath = join(destDir, '.sync-meta.json');
+    writeFile(metaPath, JSON.stringify(meta, null, 2));
+};
+const writeAssetFile = (cwd, packageName, assetType, fileName, content) => {
+    const destDir = getDestinationDir(cwd, packageName, assetType);
+    const filePath = join(destDir, fileName);
+    writeFile(filePath, content);
+};
+const cleanAssetDir = (cwd, packageName, assetType) => {
+    const destDir = getDestinationDir(cwd, packageName, assetType);
+    if (existsSync(destDir)) {
+        rmSync(destDir, { recursive: true, force: true });
+    }
+};
+const needsSync = (cwd, packageName, version) => {
+    const commandsMeta = readSyncMeta(cwd, packageName, 'commands');
+    const skillsMeta = readSyncMeta(cwd, packageName, 'skills');
+    if (!commandsMeta && !skillsMeta)
+        return true;
+    if (commandsMeta && commandsMeta.version !== version)
+        return true;
+    if (skillsMeta && skillsMeta.version !== version)
+        return true;
+    return false;
+};
+const createSyncMeta = (version, files) => ({
+    version,
+    syncedAt: new Date().toISOString(),
+    files,
+});
+
+export { cleanAssetDir, createSyncMeta, ensureDir, getDestinationDir, needsSync, parsePackageName, readSyncMeta, writeAssetFile, writeFile, writeSyncMeta };