dryai 2.1.0 → 3.0.0

package/dest/lib/sync.js

@@ -0,0 +1,503 @@
+import { Chalk } from 'chalk';
+import fs from 'fs-extra';
+import { glob } from 'glob';
+import path from 'node:path';
+import { z } from 'zod';
+import { buildSyncTargets, createAgentCmdSyncSpec, createOwnershipKey, createAgentRuleSyncSpec, describeOwnershipKey, getAgentLabel, isSyncAgent, listTargetRootPaths, SYNC_AGENTS, SYNC_ITEM_KINDS, } from './agents.js';
+import { commandFrontmatterSchema, parseFrontmatter, renderMarkdown, ruleFrontmatterSchema, validateFrontmatter, } from './frontmatter.js';
+const chalk = new Chalk({ level: 3 });
+const syncAgentSchema = z.custom((value) => typeof value === 'string' && isSyncAgent(value), {
+    message: 'Expected one configured sync agent.',
+});
+const syncManifestEntrySchema = z.object({
+    agent: syncAgentSchema,
+    kind: z.enum(SYNC_ITEM_KINDS),
+    name: z.string().min(1),
+    outputPath: z.string().min(1),
+});
+const syncManifestSchema = z.object({
+    version: z.literal(2),
+    outputs: z.array(syncManifestEntrySchema),
+});
+/**
+ * Validates and returns the agent name from a sync target, throwing if it is unrecognized.
+ */
+function parseSyncAgent(agent) {
+    if (isSyncAgent(agent)) {
+        return agent;
+    }
+    throw new Error(`Unsupported sync agent: ${agent}`);
+}
+/**
+ * Writes all command, rule, and skill outputs to their target directories, then prunes any stale dryai-managed files from prior runs.
+ */
+export async function syncToTargets(context, runtime) {
+    const { targetRoots } = context;
+    await ensureTargetDirectories(targetRoots);
+    const previousManifest = await loadSyncManifest(context.syncManifestPath);
+    const syncItems = [
+        ...(await collectCommandSyncItems(context, runtime)),
+        ...(await collectRuleSyncItems(context, runtime)),
+        ...(await collectSkillSyncItems(context)),
+    ];
+    const { syncableItems, skippedItems } = collectConflictFilterResult(syncItems);
+    const skippedOwnershipKeys = collectSkippedOwnershipKeys(skippedItems);
+    const desiredManifestEntries = collectManifestEntries(syncableItems);
+    const desiredOutputPaths = new Set(desiredManifestEntries.map((entry) => entry.outputPath));
+    const removedEntries = collectRemovedManifestEntries(previousManifest.outputs, {
+        desiredOutputPaths,
+        skippedOwnershipKeys,
+    });
+    await removeStaleOutputs(removedEntries);
+    const appliedItems = [];
+    for (const syncItem of syncableItems) {
+        appliedItems.push(await applySyncItem(syncItem));
+    }
+    const preservedEntries = collectPreservedManifestEntries(previousManifest.outputs, {
+        desiredOutputPaths,
+        skippedOwnershipKeys,
+    });
+    await saveSyncManifest(context.syncManifestPath, createSyncManifest([...desiredManifestEntries, ...preservedEntries]));
+    runtime.logInfo(renderSyncReport(appliedItems, removedEntries, skippedItems));
+}
+/**
+ * Derives the ownership key claimed by one sync target for conflict detection.
+ */
+function deriveOwnershipKeyForSyncTarget(syncItem, target) {
+    return createOwnershipKey(parseSyncAgent(target.agent), syncItem.kind, {
+        name: syncItem.name,
+        outputPath: target.outputPath,
+    });
+}
+/**
+ * Returns the ownership key for a saved manifest entry.
+ */
+function deriveOwnershipKeyForManifestEntry(manifestEntry) {
+    return createOwnershipKey(manifestEntry.agent, manifestEntry.kind, {
+        name: manifestEntry.name,
+        outputPath: manifestEntry.outputPath,
+    });
+}
+/**
+ * Ensures that all target root directories exist before generated files are written.
+ */
+async function ensureTargetDirectories(targetRoots) {
+    await Promise.all(listTargetRootPaths(targetRoots).map(fs.ensureDir));
+}
+/**
+ * Reads the sync manifest from disk, or returns an empty manifest if none exists yet.
+ */
+async function loadSyncManifest(manifestPath) {
+    if (!(await fs.pathExists(manifestPath))) {
+        return createSyncManifest([]);
+    }
+    const rawManifest = await fs.readFile(manifestPath, 'utf8');
+    const parsedManifest = JSON.parse(rawManifest);
+    return syncManifestSchema.parse(parsedManifest);
+}
+/**
+ * Serializes and writes the sync manifest to manifestPath.
+ */
+async function saveSyncManifest(manifestPath, manifest) {
+    await fs.ensureDir(path.dirname(manifestPath));
+    await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}
+/**
+ * Creates a normalized sync manifest with deterministic output ordering.
+ */
+function createSyncManifest(entries) {
+    const entriesByOutputPath = new Map();
+    for (const entry of entries) {
+        entriesByOutputPath.set(entry.outputPath, entry);
+    }
+    return {
+        version: 2,
+        outputs: [...entriesByOutputPath.values()].sort(compareManifestEntries),
+    };
+}
+/**
+ * Returns the markdown source files found directly under a source root.
+ */
+async function collectMarkdownFiles(rootDir) {
+    await fs.ensureDir(rootDir);
+    const matches = await glob([path.join(rootDir, '*.md')]);
+    return matches.sort();
+}
+/**
+ * Writes one markdown file after rendering its frontmatter and body content.
+ */
+async function writeMarkdownFile(filePath, metadata, body) {
+    await fs.ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, renderMarkdown({ metadata, body }), 'utf8');
+}
+/**
+ * Detects whether each agent target for one item will be installed or updated.
+ */
+async function detectSyncChanges(syncItem) {
+    return Promise.all(syncItem.targets.map(async (target) => ({
+        agent: parseSyncAgent(target.agent),
+        changeType: (await fs.pathExists(target.outputPath))
+            ? 'updated'
+            : 'installed',
+    })));
+}
+/**
+ * Applies one sync item and records the change type for each agent target.
+ */
+async function applySyncItem(syncItem) {
+    const changes = await detectSyncChanges(syncItem);
+    await writeSyncItem(syncItem);
+    return {
+        item: syncItem,
+        changes,
+    };
+}
+/**
+ * Writes one sync target to its output path, either as a markdown file or a directory copy.
+ */
+async function writeSyncTarget(target) {
+    if (target.targetType === 'markdown') {
+        await writeMarkdownFile(target.writePath, target.metadata, target.body);
+        return;
+    }
+    await copyDirectoryContents(target.sourceDir, target.outputPath);
+}
+/**
+ * Writes one sync item to all of its target outputs.
+ */
+async function writeSyncItem(syncItem) {
+    for (const target of syncItem.targets) {
+        await writeSyncTarget(target);
+    }
+}
+/**
+ * Collects sync operations for command sources after validating their frontmatter.
+ */
+async function collectCommandSyncItems(context, runtime) {
+    const { targetRoots } = context;
+    const commandFiles = await collectMarkdownFiles(context.sourceRoots.commands);
+    const syncItems = [];
+    for (const filePath of commandFiles) {
+        const fileName = path.basename(filePath, '.md');
+        const rawContent = await fs.readFile(filePath, 'utf8');
+        const { metadata, body } = parseFrontmatter(rawContent);
+        const commandMetadata = validateFrontmatter(runtime, {
+            filePath,
+            metadata,
+            schema: commandFrontmatterSchema,
+        });
+        if (!commandMetadata) {
+            continue;
+        }
+        const commandName = commandMetadata.name;
+        const commandInput = createAgentCmdSyncSpec(runtime, {
+            filePath,
+            sourceFileStem: fileName,
+            body,
+            frontmatter: commandMetadata,
+        });
+        if (!commandInput) {
+            continue;
+        }
+        syncItems.push({
+            kind: 'command',
+            name: commandName,
+            sourcePath: filePath,
+            targets: buildSyncTargets({
+                kind: 'command',
+                input: commandInput,
+                targetRoots,
+            }),
+        });
+    }
+    return syncItems;
+}
+/**
+ * Collects sync operations for rule sources after validating their frontmatter.
+ */
+async function collectRuleSyncItems(context, runtime) {
+    const { targetRoots } = context;
+    const ruleFiles = await collectMarkdownFiles(context.sourceRoots.rules);
+    const syncItems = [];
+    for (const filePath of ruleFiles) {
+        const fileName = path.basename(filePath, '.md');
+        const rawContent = await fs.readFile(filePath, 'utf8');
+        const { metadata, body } = parseFrontmatter(rawContent);
+        const ruleMetadata = validateFrontmatter(runtime, {
+            filePath,
+            metadata,
+            schema: ruleFrontmatterSchema,
+        });
+        if (!ruleMetadata) {
+            continue;
+        }
+        const ruleInput = createAgentRuleSyncSpec(runtime, {
+            filePath,
+            sourceFileStem: fileName,
+            body,
+            frontmatter: ruleMetadata,
+        });
+        if (!ruleInput) {
+            continue;
+        }
+        syncItems.push({
+            kind: 'rule',
+            name: fileName,
+            sourcePath: filePath,
+            targets: buildSyncTargets({
+                kind: 'rule',
+                input: ruleInput,
+                targetRoots,
+            }),
+        });
+    }
+    return syncItems;
+}
+/**
+ * Collects sync operations for local skill directories.
+ */
+async function collectSkillSyncItems(context) {
+    const { targetRoots } = context;
+    await fs.ensureDir(context.sourceRoots.skills);
+    const entries = await fs.readdir(context.sourceRoots.skills, {
+        withFileTypes: true,
+    });
+    const syncItems = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const sourceDir = path.join(context.sourceRoots.skills, entry.name);
+        syncItems.push({
+            kind: 'skill',
+            name: entry.name,
+            sourcePath: sourceDir,
+            targets: buildSyncTargets({
+                kind: 'skill',
+                input: {
+                    name: entry.name,
+                    sourceDir,
+                },
+                targetRoots,
+            }),
+        });
+    }
+    return syncItems;
+}
+/**
+ * Clears targetDir and copies all direct entries from sourceDir into it.
+ */
+async function copyDirectoryContents(sourceDir, targetDir) {
+    await fs.emptyDir(targetDir);
+    const entryNames = await fs.readdir(sourceDir);
+    for (const entryName of entryNames) {
+        await fs.copy(path.join(sourceDir, entryName), path.join(targetDir, entryName));
+    }
+}
+/**
+ * Collects the syncable and skipped items after analyzing output namespace conflicts.
+ */
+function collectConflictFilterResult(items) {
+    const ownershipMap = new Map();
+    for (const item of items) {
+        for (const ownershipKey of collectOwnershipKeys(item)) {
+            const existingOwners = ownershipMap.get(ownershipKey);
+            if (existingOwners) {
+                existingOwners.push(item);
+            }
+            else {
+                ownershipMap.set(ownershipKey, [item]);
+            }
+        }
+    }
+    const skippedItemsBySourcePath = new Map();
+    for (const [ownershipKey, owners] of ownershipMap) {
+        if (owners.length < 2) {
+            continue;
+        }
+        const conflictDescription = describeOwnershipKey(ownershipKey);
+        for (const owner of owners) {
+            const existingSkippedItem = skippedItemsBySourcePath.get(owner.sourcePath);
+            if (existingSkippedItem) {
+                existingSkippedItem.conflictDescriptions.push(conflictDescription);
+            }
+            else {
+                skippedItemsBySourcePath.set(owner.sourcePath, {
+                    item: owner,
+                    conflictDescriptions: [conflictDescription],
+                });
+            }
+        }
+    }
+    const skippedItems = [...skippedItemsBySourcePath.values()].map((skippedItem) => ({
+        item: skippedItem.item,
+        conflictDescriptions: [
+            ...new Set(skippedItem.conflictDescriptions),
+        ].sort(),
+    }));
+    const skippedSourcePaths = new Set(skippedItems.map((skippedItem) => skippedItem.item.sourcePath));
+    return {
+        syncableItems: items.filter((item) => !skippedSourcePaths.has(item.sourcePath)),
+        skippedItems,
+    };
+}
+/**
+ * Returns the ownership keys used to detect namespace conflicts for one sync item.
+ */
+function collectOwnershipKeys(syncItem) {
+    return syncItem.targets.map((target) => deriveOwnershipKeyForSyncTarget(syncItem, target));
+}
+/**
+ * Returns the set of ownership keys whose items were skipped due to conflicts.
+ */
+function collectSkippedOwnershipKeys(skippedItems) {
+    const ownershipKeys = skippedItems.flatMap((skippedItem) => collectOwnershipKeys(skippedItem.item));
+    return new Set(ownershipKeys);
+}
+/**
+ * Converts sync items into manifest entries for the current desired outputs.
+ */
+function collectManifestEntries(syncItems) {
+    return syncItems.flatMap((syncItem) => syncItem.targets.map((target) => ({
+        agent: parseSyncAgent(target.agent),
+        kind: syncItem.kind,
+        name: syncItem.name,
+        outputPath: target.outputPath,
+    })));
+}
+/**
+ * Returns the manifest entries that should be removed because they are no longer desired.
+ */
+function collectRemovedManifestEntries(manifestEntries, input) {
+    return manifestEntries.filter((entry) => !input.desiredOutputPaths.has(entry.outputPath) &&
+        !input.skippedOwnershipKeys.has(deriveOwnershipKeyForManifestEntry(entry)));
+}
+/**
+ * Returns manifest entries for skipped source items due to a conflict.
+ */
+function collectPreservedManifestEntries(manifestEntries, input) {
+    return manifestEntries.filter((entry) => !input.desiredOutputPaths.has(entry.outputPath) &&
+        input.skippedOwnershipKeys.has(deriveOwnershipKeyForManifestEntry(entry)));
+}
+/**
+ * Removes stale dryai-managed outputs that are no longer part of the desired sync state.
+ */
+async function removeStaleOutputs(removedEntries) {
+    for (const entry of removedEntries) {
+        await fs.remove(entry.outputPath);
+    }
+}
+/**
+ * Renders a sync summary grouped by agent, item kind, and skipped conflicts.
+ */
+function renderSyncReport(appliedItems, removedEntries, skippedItems) {
+    const sections = [chalk.bold.cyan('Applied changes:')];
+    for (const agent of SYNC_AGENTS) {
+        sections.push(renderAgentSyncSection(getAgentLabel(agent), collectAgentReportedSyncChanges(appliedItems, removedEntries, agent)));
+    }
+    if (skippedItems.length === 0) {
+        sections.push(`${chalk.bold.green('Skipped conflicts:')} ${chalk.green('None')}`);
+    }
+    else {
+        const skippedLines = skippedItems
+            .slice()
+            .sort((left, right) => formatSyncItemLabel(left.item).localeCompare(formatSyncItemLabel(right.item)))
+            .map((skippedItem) => [
+            `- ${chalk.red(formatSyncItemLabel(skippedItem.item))}`,
+            `  * ${chalk.bold.red('due to:')} ${chalk.yellow(skippedItem.conflictDescriptions.join(', '))}`,
+        ].join('\n'));
+        sections.push(`${chalk.bold.red('Skipped conflicts:')}\n${skippedLines.join('\n')}`);
+    }
+    return sections.join('\n\n');
+}
+/**
+ * Collects the reported sync changes relevant to one agent.
+ */
+function collectAgentReportedSyncChanges(appliedItems, removedEntries, agent) {
+    const appliedChanges = appliedItems.flatMap((appliedItem) => appliedItem.changes
+        .filter((change) => change.agent === agent)
+        .map((change) => ({
+        kind: appliedItem.item.kind,
+        name: appliedItem.item.name,
+        changeType: change.changeType,
+    })));
+    const removedChanges = removedEntries
+        .filter((entry) => entry.agent === agent)
+        .map((entry) => ({
+        kind: entry.kind,
+        name: entry.name,
+        changeType: 'removed',
+    }));
+    return [...appliedChanges, ...removedChanges];
+}
+/**
+ * Renders the synced items for one agent grouped by item kind.
+ */
+function renderAgentSyncSection(agentLabel, reportedChanges) {
+    const kindSections = [
+        renderKindSyncLine('commands', 'command', reportedChanges),
+        renderKindSyncLine('rules', 'rule', reportedChanges),
+        renderKindSyncLine('skills', 'skill', reportedChanges),
+    ].filter((section) => section !== undefined);
+    return [`- ${colorAgentLabel(agentLabel)}`, ...kindSections].join('\n');
+}
+/**
+ * Renders one sync summary section for a specific item kind.
+ */
+function renderKindSyncLine(label, kind, reportedChanges) {
+    const matchingChanges = reportedChanges
+        .filter((item) => item.kind === kind)
+        .slice()
+        .sort((left, right) => left.name.localeCompare(right.name));
+    if (matchingChanges.length === 0) {
+        return undefined;
+    }
+    return [
+        `  * ${colorKindLabel(label)}`,
+        ...matchingChanges.map(renderReportedSyncChangeLine),
+    ].join('\n');
+}
+/**
+ * Returns the styled agent label used in the sync summary.
+ */
+function colorAgentLabel(agentLabel) {
+    return chalk.bold.blue(agentLabel);
+}
+/**
+ * Returns the styled item-kind label used in the sync summary.
+ */
+function colorKindLabel(label) {
+    return chalk.bold.yellow(label);
+}
+/**
+ * Returns the styled change-type label used in the sync summary.
+ */
+function colorChangeType(changeType) {
+    if (changeType === 'installed') {
+        return chalk.green(changeType);
+    }
+    if (changeType === 'removed') {
+        return chalk.red(changeType);
+    }
+    return chalk.yellow(changeType);
+}
+/**
+ * Renders one styled applied-item line in the sync summary.
+ */
+function renderReportedSyncChangeLine(reportedChange) {
+    return `    - ${chalk.whiteBright(reportedChange.name)} (${colorChangeType(reportedChange.changeType)})`;
+}
+/**
+ * Returns a readable label for one sync item in conflict warnings.
+ */
+function formatSyncItemLabel(item) {
+    return `${item.kind} "${item.name}" from ${item.sourcePath}`;
+}
+/**
+ * Orders manifest entries deterministically for stable on-disk state.
+ */
+function compareManifestEntries(left, right) {
+    return [left.agent, left.kind, left.name, left.outputPath]
+        .join('\0')
+        .localeCompare([right.agent, right.kind, right.name, right.outputPath].join('\0'));
+}

package/dest/main.js

@@ -1,18 +1,9 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
-import { runInstallCommand } from './commands/install.js';
-import { addSkillsCommand } from './commands/skills/index.js';
-import { nonEmptyOptionStringSchema, parseOptionValue, parseOptionsObject, } from './lib/command-options.js';
-import { createAgentsContext, resolveRequestedConfigRoot, resolveRequestedOutputRoot, } from './lib/context.js';
-const rootOptionsSchema = z.object({
-    test: z.boolean().optional().default(false),
-    configRoot: nonEmptyOptionStringSchema.optional(),
-    outputRoot: nonEmptyOptionStringSchema.optional(),
-});
+import { runCLI } from './cli.js';
 const EXECUTABLE_NAME = 'dryai';
 /**
  * Reads the CLI version from the package manifest at the repository root.
@@ -28,85 +19,14 @@ async function readCliVersion() {
     return packageJsonSchema.parse(parsedPackageJson).version;
 }
 /**
- * Parses the top-level CLI options into a validated shape.
- */
-function getRootOptions(program) {
-    return parseOptionsObject({
-        schema: rootOptionsSchema,
-        options: program.opts(),
-        optionsLabel: 'root options',
-    });
-}
-/**
- * Returns the active context after applying root-level input and output
- * overrides.
- */
-function resolveActiveContext(program) {
-    const rootOptions = getRootOptions(program);
-    const requestedConfigRoot = resolveRequestedConfigRoot({
-        ...(rootOptions.configRoot ? { configRoot: rootOptions.configRoot } : {}),
-    });
-    const requestedOutputRoot = resolveRequestedOutputRoot({
-        test: rootOptions.test,
-        ...(rootOptions.outputRoot ? { outputRoot: rootOptions.outputRoot } : {}),
-    });
-    const context = createAgentsContext({
-        ...(requestedConfigRoot ? { inputRoot: requestedConfigRoot } : {}),
-        ...(requestedOutputRoot ? { outputRoot: requestedOutputRoot } : {}),
-    });
-    return context;
-}
-/**
- * Configures and runs the agents CLI entrypoint.
+ * Configures and runs the executable CLI entrypoint with the production CLI options.
  */
 async function main() {
-    const program = new Command();
-    const cliVersion = await readCliVersion();
-    program
-        .name(EXECUTABLE_NAME)
-        .usage('[options] <command> [args]')
-        .helpOption('-h, --help', 'Display this message')
-        .version(cliVersion, '-v, --version', 'Display the current version')
-        .option('--test', 'Shortcut for writing generated output into ./output-test unless --output-root is also provided')
-        .option('--config-root <path>', 'Read configs from a different root instead of ~/.config/dryai', parseOptionValue({
-        schema: nonEmptyOptionStringSchema,
-        optionLabel: '--config-root',
-    }))
-        .option('--output-root <path>', 'Write generated output under a different root instead of the default home directory', parseOptionValue({
-        schema: nonEmptyOptionStringSchema,
-        optionLabel: '--output-root',
-    }))
-        .helpCommand(false)
-        .action(() => {
-        program.outputHelp();
-    });
-    program
-        .command('install')
-        .description('Install generated output into Copilot and Cursor targets')
-        .usage('install')
-        .action(async () => {
-        const activeContext = resolveActiveContext(program);
-        await runInstallCommand(activeContext);
-        if (requestedOutputRootWasUsed(program)) {
-            console.log(`Generated output written to ${activeContext.outputRoot}`);
-        }
-    });
-    addSkillsCommand({
-        parent: program,
-        commandName: `${EXECUTABLE_NAME} skills`,
-        resolveContext: () => resolveActiveContext(program),
+    await runCLI({
+        argv: process.argv.slice(2),
+        executableName: EXECUTABLE_NAME,
+        version: await readCliVersion(),
     });
-    await program.parseAsync(process.argv);
-}
-/**
- * Returns whether the current invocation requested a non-default output root.
- */
-function requestedOutputRootWasUsed(program) {
-    const rootOptions = getRootOptions(program);
-    return (resolveRequestedOutputRoot({
-        test: rootOptions.test,
-        ...(rootOptions.outputRoot ? { outputRoot: rootOptions.outputRoot } : {}),
-    }) !== undefined);
 }
 try {
     await main();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dryai",
-  "version": "2.1.0",
-  "description": "CLI for installing shared AI commands, rules, and skills into Copilot and Cursor.",
+  "version": "3.0.0",
+  "description": "CLI for syncing shared AI commands, rules, and skills into supported agent targets.",
   "type": "module",
   "repository": {
     "type": "git",
@@ -35,7 +35,7 @@
     "glob": "^13.0.6",
     "gray-matter": "^4.0.3",
     "simple-git": "^3.35.2",
-    "zod": "^3.24.1"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@commitlint/cli": "^20.5.0",

package/dest/commands/install.d.ts

@@ -1,3 +0,0 @@
-import type { AgentsContext } from '../lib/context.js';
-export declare function runInstallCommand(context: AgentsContext): Promise<void>;
-//# sourceMappingURL=install.d.ts.map

package/dest/commands/install.js

@@ -1,4 +0,0 @@
-import { installToTargets } from '../lib/install.js';
-export async function runInstallCommand(context) {
-    await installToTargets(context, { targetRoots: context.targetRoots });
-}

package/dest/lib/install.d.ts

@@ -1,8 +0,0 @@
-import type { AgentsContext, TargetRoots } from './context.js';
-/**
- * Installs all generated command, rule, and skill outputs into the requested targets.
- */
-export declare function installToTargets(context: AgentsContext, { targetRoots }: {
-    targetRoots: TargetRoots;
-}): Promise<void>;
-//# sourceMappingURL=install.d.ts.map