rubrkit 0.1.1 → 0.3.0

package/src/pull.js

@@ -1,676 +1,682 @@
-import fs from 'node:fs';
-import fsp from 'node:fs/promises';
-import path from 'node:path';
-import readline from 'node:readline/promises';
-
-import { RubrkitApiClient } from './api.js';
-import { resolveAgentAdapter } from './adapters.js';
-import { authError, RubrkitCliError } from './errors.js';
-import {
-    findManifestEntry,
-    hashContent,
-    loadManifest,
-    removeManifestEntriesByDestination,
-    upsertManifestEntry,
-    writeManifest,
-} from './manifest.js';
-import { normalizeArtifactPath, relativeToRoot, resolveInsideRoot, slugifyPathSegment } from './pathSafety.js';
-import { promptForPullSelections } from './prompts.js';
-
-/**
- * @param {{
- *   config: Awaited<ReturnType<import('./config.js').resolveConfig>>,
- *   stdin?: NodeJS.ReadableStream,
- *   stdout?: NodeJS.WritableStream,
- *   stderr?: NodeJS.WritableStream,
- *   fetchImpl?: typeof fetch,
- *   fsImpl?: typeof fsp,
- *   fsSyncImpl?: Pick<typeof fs, 'existsSync'>,
- * }} params
- */
-export async function runPull({
-    config,
-    stdin = process.stdin,
-    stdout = process.stdout,
-    fetchImpl = globalThis.fetch,
-    fsImpl = fsp,
-    fsSyncImpl = fs,
-}) {
-    if (!config.apiKey) {
-        throw authError('Missing Rubrkit API key. Set RUBRKIT_API_KEY or pass --api-key.');
-    }
-
-    const destinationRoot = path.resolve(config.destination);
-    const apiClient = new RubrkitApiClient({
-        apiUrl: config.apiUrl,
-        apiKey: config.apiKey,
-        fetchImpl,
-    });
-    const manifest = await loadManifest(destinationRoot, fsImpl);
-    const bundles = await apiClient.listArtifactBundles();
-    const selections = await resolveSelections({
-        config,
-        apiClient,
-        bundles,
-        manifest,
-        stdin,
-        stdout,
-    });
-
-    if (selections.length === 0) {
-        stdout.write('No artifacts matched the pull request.\n');
-        return;
-    }
-
-    const hydrated = await hydrateSelections({ apiClient, selections });
-    const plan = await createPullPlan({
-        destinationRoot,
-        items: hydrated,
-        manifest,
-        config,
-        fsImpl,
-        fsSyncImpl,
-    });
-
-    printPlan({ plan, destinationRoot, dryRun: config.dryRun, stdout });
-
-    const conflicts = plan.actions.filter((action) => action.blocked);
-
-    if (conflicts.length > 0 && !config.dryRun) {
-        throw new RubrkitCliError(
-            `Pull stopped because ${conflicts.length} local change${conflicts.length === 1 ? '' : 's'} would be overwritten. Re-run with --force to overwrite.`,
-            { code: 'local_changes_protected' },
-        );
-    }
-
-    if (config.dryRun) {
-        return;
-    }
-
-    await applyPlan({ plan, manifest, destinationRoot, fsImpl });
-
-    stdout.write(
-        `Rubrkit pull complete: ${plan.summary.writes} written, ${plan.summary.skips} skipped, ${plan.summary.prunes} pruned.\n`,
-    );
-}
-
-/**
- * @param {{
- *   config: Awaited<ReturnType<import('./config.js').resolveConfig>>,
- *   apiClient: RubrkitApiClient,
- *   bundles: Array<Record<string, any>>,
- *   manifest: Awaited<ReturnType<typeof loadManifest>>,
- *   stdin: NodeJS.ReadableStream,
- *   stdout: NodeJS.WritableStream,
- * }} params
- */
-async function resolveSelections({ config, apiClient, bundles, manifest, stdin, stdout }) {
-    const fileCache = new Map();
-    const loadFiles = async (bundle) => {
-        if (!fileCache.has(bundle.id)) {
-            fileCache.set(bundle.id, await apiClient.listFiles(bundle.id));
-        }
-
-        return fileCache.get(bundle.id);
-    };
-
-    if (config.updateOnly) {
-        return resolveUpdateOnlySelections({ config, bundles, manifest, loadFiles });
-    }
-
-    if (config.all) {
-        if (!config.yes) {
-            await confirmAll({ bundleCount: bundles.length, stdin, stdout });
-        }
-
-        return selectAll({ bundles, loadFiles });
-    }
-
-    if (config.artifactBundle || config.artifact) {
-        return resolveFlagSelections({ config, bundles, loadFiles });
-    }
-
-    if (config.selector) {
-        return resolveSelectorSelections({ selector: config.selector, yes: config.yes, bundles, loadFiles });
-    }
-
-    if (config.yes) {
-        throw new RubrkitCliError('No selector was provided. Use "all", --artifact-bundle, or --artifact with --yes.', {
-            code: 'selector_required',
-            exitCode: 2,
-        });
-    }
-
-    return promptForPullSelections({ bundles, loadFiles, stdin, stdout });
-}
-
-/**
- * @param {{ bundleCount: number, stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream }} params
- */
-async function confirmAll({ bundleCount, stdin, stdout }) {
-    const rl = readline.createInterface({ input: stdin, output: stdout });
-
-    try {
-        const answer = await rl.question(`Pull all files from ${bundleCount} artifact bundle${bundleCount === 1 ? '' : 's'}? [y/N] `);
-
-        if (!['y', 'yes'].includes(answer.trim().toLowerCase())) {
-            throw new RubrkitCliError('Pull cancelled.', { code: 'pull_cancelled', exitCode: 2 });
-        }
-    } finally {
-        rl.close();
-    }
-}
-
-/**
- * @param {{ bundles: Array<Record<string, any>>, loadFiles(bundle: Record<string, any>): Promise<Array<Record<string, any>>> }} params
- */
-async function selectAll({ bundles, loadFiles }) {
-    const selections = [];
-
-    for (const bundle of bundles) {
-        const files = await loadFiles(bundle);
-
-        for (const file of files) {
-            selections.push({ artifactBundle: bundle, file });
-        }
-    }
-
-    return selections;
-}
-
-/**
- * @param {{
- *   config: Awaited<ReturnType<import('./config.js').resolveConfig>>,
- *   bundles: Array<Record<string, any>>,
- *   loadFiles(bundle: Record<string, any>): Promise<Array<Record<string, any>>>,
- * }} params
- */
-async function resolveFlagSelections({ config, bundles, loadFiles }) {
-    const selectedBundles = config.artifactBundle ? findBundles(bundles, config.artifactBundle) : bundles;
-
-    if (selectedBundles.length === 0) {
-        throw new RubrkitCliError(`No artifact bundle matched "${config.artifactBundle}".`, { code: 'artifact_bundle_not_found' });
-    }
-
-    const selections = [];
-
-    for (const bundle of selectedBundles) {
-        const files = await loadFiles(bundle);
-        const selectedFiles = config.artifact ? findFiles(files, config.artifact) : files;
-
-        for (const file of selectedFiles) {
-            selections.push({ artifactBundle: bundle, file });
-        }
-    }
-
-    if (config.artifact && selections.length === 0) {
-        throw new RubrkitCliError(`No artifact matched "${config.artifact}".`, { code: 'artifact_not_found' });
-    }
-
-    if (config.yes && selectedBundles.length > 1 && config.artifactBundle) {
-        throw new RubrkitCliError(`Artifact bundle selector "${config.artifactBundle}" is ambiguous.`, {
-            code: 'ambiguous_selector',
-            exitCode: 2,
-        });
-    }
-
-    return selections;
-}
-
-/**
- * @param {{
- *   selector: string,
- *   yes: boolean,
- *   bundles: Array<Record<string, any>>,
- *   loadFiles(bundle: Record<string, any>): Promise<Array<Record<string, any>>>,
- * }} params
- */
-async function resolveSelectorSelections({ selector, yes, bundles, loadFiles }) {
-    const bundleMatches = findBundles(bundles, selector);
-    const fileMatches = [];
-
-    for (const bundle of bundles) {
-        const files = await loadFiles(bundle);
-
-        for (const file of findFiles(files, selector)) {
-            fileMatches.push({ artifactBundle: bundle, file });
-        }
-    }
-
-    const candidateCount = bundleMatches.length + fileMatches.length;
-
-    if (candidateCount === 0) {
-        throw new RubrkitCliError(`No artifact bundle or artifact matched "${selector}".`, { code: 'selector_not_found' });
-    }
-
-    if (candidateCount > 1 && yes) {
-        throw new RubrkitCliError(`Selector "${selector}" is ambiguous. Use --artifact-bundle or --artifact.`, {
-            code: 'ambiguous_selector',
-            exitCode: 2,
-        });
-    }
-
-    if (bundleMatches.length === 1 && fileMatches.length === 0) {
-        const files = await loadFiles(bundleMatches[0]);
-        return files.map((file) => ({ artifactBundle: bundleMatches[0], file }));
-    }
-
-    if (fileMatches.length === 1 && bundleMatches.length === 0) {
-        return fileMatches;
-    }
-
-    throw new RubrkitCliError(`Selector "${selector}" is ambiguous. Use --artifact-bundle or --artifact.`, {
-        code: 'ambiguous_selector',
-        exitCode: 2,
-    });
-}
-
-/**
- * @param {{
- *   config: Awaited<ReturnType<import('./config.js').resolveConfig>>,
- *   bundles: Array<Record<string, any>>,
- *   manifest: Awaited<ReturnType<typeof loadManifest>>,
- *   loadFiles(bundle: Record<string, any>): Promise<Array<Record<string, any>>>,
- * }} params
- */
-async function resolveUpdateOnlySelections({ config, bundles, manifest, loadFiles }) {
-    const entries = manifest.entries.filter((entry) => matchesEntrySelectors(entry, config));
-    const selections = [];
-
-    for (const entry of entries) {
-        const bundle = bundles.find((candidate) => candidate.id === entry.artifactBundleId);
-
-        if (!bundle) {
-            continue;
-        }
-
-        const files = await loadFiles(bundle);
-        const file = files.find((candidate) => candidate.id === entry.artifactId || candidate.path === entry.artifactPath);
-
-        if (file) {
-            selections.push({ artifactBundle: bundle, file });
-        }
-    }
-
-    return selections;
-}
-
-/**
- * @param {Record<string, any>} entry
- * @param {Awaited<ReturnType<import('./config.js').resolveConfig>>} config
- */
-function matchesEntrySelectors(entry, config) {
-    const selector = config.selector && config.selector !== 'all' ? config.selector : null;
-    const bundleSelector = config.artifactBundle ?? selector;
-    const artifactSelector = config.artifact ?? (bundleSelector === selector ? null : selector);
-    const bundleMatches = !bundleSelector || [entry.artifactBundleId, entry.artifactBundleName].some((value) => matchesSelector(value, bundleSelector));
-    const artifactMatches =
-        !artifactSelector ||
-        [entry.artifactId, entry.artifactPath, path.posix.basename(String(entry.artifactPath ?? ''))].some((value) =>
-            matchesSelector(value, artifactSelector),
-        );
-
-    return bundleMatches && artifactMatches;
-}
-
-/**
- * @param {Array<Record<string, any>>} bundles
- * @param {string} selector
- */
-function findBundles(bundles, selector) {
-    return bundles.filter((bundle) => {
-        const slug = slugifyPathSegment(bundle.name ?? bundle.id);
-
-        return [bundle.id, bundle.name, slug].some((value) => matchesSelector(value, selector));
-    });
-}
-
-/**
- * @param {Array<Record<string, any>>} files
- * @param {string} selector
- */
-function findFiles(files, selector) {
-    return files.filter((file) => {
-        const normalizedPath = normalizeArtifactPath(file.path);
-
-        return [file.id, normalizedPath, path.posix.basename(normalizedPath)].some((value) => matchesSelector(value, selector));
-    });
-}
-
-/**
- * @param {unknown} value
- * @param {string} selector
- */
-function matchesSelector(value, selector) {
-    if (typeof value !== 'string') {
-        return false;
-    }
-
-    return value === selector || value.toLowerCase() === selector.toLowerCase();
-}
-
-/**
- * @param {{ apiClient: RubrkitApiClient, selections: Array<{ artifactBundle: Record<string, any>, file: Record<string, any> }> }} params
- */
-async function hydrateSelections({ apiClient, selections }) {
-    const hydrated = [];
-
-    for (const selection of selections) {
-        const detail = await apiClient.getFile(selection.artifactBundle.id, selection.file.id);
-
-        hydrated.push({
-            artifactBundle: selection.artifactBundle,
-            file: detail.file ?? selection.file,
-            version: detail.version ?? {},
-            content: typeof detail.content === 'string' ? detail.content : '',
-        });
-    }
-
-    return hydrated;
-}
-
-/**
- * @param {{
- *   destinationRoot: string,
- *   items: Array<{ artifactBundle: Record<string, any>, file: Record<string, any>, version: Record<string, any>, content: string }>,
- *   manifest: Awaited<ReturnType<typeof loadManifest>>,
- *   config: Awaited<ReturnType<import('./config.js').resolveConfig>>,
- *   fsImpl: typeof fsp,
- *   fsSyncImpl: Pick<typeof fs, 'existsSync'>,
- * }} params
- */
-async function createPullPlan({ destinationRoot, items, manifest, config, fsImpl, fsSyncImpl }) {
-    const adapter = resolveAgentAdapter({
-        root: destinationRoot,
-        requestedAgent: config.agent,
-        fsImpl: fsSyncImpl,
-    });
-    const actions = [];
-    const selectedDestinationPaths = new Set();
-    const selectedBundleIds = new Set(items.map((item) => item.artifactBundle.id));
-
-    for (const item of items) {
-        const placement = adapter.place({
-            artifactBundle: item.artifactBundle,
-            file: item.file,
-            exists(relativePath) {
-                return fsSyncImpl.existsSync(resolveInsideRoot(destinationRoot, relativePath));
-            },
-        });
-        const targetPath = resolveInsideRoot(destinationRoot, placement.destinationPath);
-        const destinationPath = relativeToRoot(destinationRoot, targetPath);
-        selectedDestinationPaths.add(destinationPath);
-
-        actions.push(
-            await createWriteAction({
-                adapterName: adapter.name,
-                destinationRoot,
-                destinationPath,
-                targetPath,
-                placementReason: placement.reason,
-                item,
-                manifest,
-                config,
-                fsImpl,
-            }),
-        );
-    }
-
-    if (config.prune) {
-        for (const entry of manifest.entries) {
-            const destinationPath = String(entry.destinationPath ?? '');
-
-            if (!selectedBundleIds.has(entry.artifactBundleId) || selectedDestinationPaths.has(destinationPath)) {
-                continue;
-            }
-
-            const targetPath = resolveInsideRoot(destinationRoot, destinationPath);
-            actions.push(await createPruneAction({ destinationRoot, destinationPath, targetPath, entry, config, fsImpl }));
-        }
-    }
-
-    const summary = {
-        writes: actions.filter((action) => ['write', 'overwrite', 'update'].includes(action.action)).length,
-        skips: actions.filter((action) => action.action === 'skip').length,
-        prunes: actions.filter((action) => action.action === 'prune').length,
-        conflicts: actions.filter((action) => action.blocked).length,
-    };
-
-    return { adapterName: adapter.name, actions, summary };
-}
-
-/**
- * @param {{
- *   adapterName: string,
- *   destinationRoot: string,
- *   destinationPath: string,
- *   targetPath: string,
- *   placementReason: string,
- *   item: { artifactBundle: Record<string, any>, file: Record<string, any>, version: Record<string, any>, content: string },
- *   manifest: Awaited<ReturnType<typeof loadManifest>>,
- *   config: Awaited<ReturnType<import('./config.js').resolveConfig>>,
- *   fsImpl: typeof fsp,
- * }} params
- */
-async function createWriteAction({ adapterName, destinationRoot, destinationPath, targetPath, placementReason, item, manifest, config, fsImpl }) {
-    const existingContent = await readTextIfExists(targetPath, fsImpl);
-    const localHash = existingContent === null ? null : hashContent(existingContent);
-    const remoteHash = item.version.contentHash ?? item.file.contentHash ?? hashContent(item.content);
-    const manifestEntry = findManifestEntry(manifest, {
-        artifactBundleId: item.artifactBundle.id,
-        artifactId: item.file.id,
-        destinationPath,
-    });
-    const base = {
-        kind: 'write',
-        action: 'write',
-        adapterName,
-        destinationPath,
-        targetPath,
-        placementReason,
-        artifactBundle: item.artifactBundle,
-        file: item.file,
-        version: item.version,
-        content: item.content,
-        remoteHash,
-        localHash,
-        manifestEntry,
-        blocked: false,
-        reason: '',
-    };
-
-    if (manifestEntry) {
-        const expectedHash = String(manifestEntry.lastKnownLocalContentHash ?? '');
-
-        if (localHash && expectedHash && localHash !== expectedHash && !config.force) {
-            return {
-                ...base,
-                action: 'conflict',
-                blocked: true,
-                reason: 'local changes differ from the last Rubrkit pull',
-            };
-        }
-
-        if (localHash === remoteHash && manifestEntry.contentHash === remoteHash) {
-            return {
-                ...base,
-                action: 'skip',
-                reason: 'already up to date',
-            };
-        }
-
-        return {
-            ...base,
-            action: existingContent === null ? 'write' : 'update',
-            reason: existingContent === null ? 'tracked file is missing locally' : 'remote artifact changed',
-        };
-    }
-
-    if (config.updateOnly) {
-        return {
-            ...base,
-            action: 'skip',
-            reason: 'not tracked in the local manifest',
-        };
-    }
-
-    if (existingContent !== null && !config.force) {
-        return {
-            ...base,
-            action: 'conflict',
-            blocked: true,
-            reason: 'destination exists and is not managed by Rubrkit',
-        };
-    }
-
-    return {
-        ...base,
-        action: existingContent === null ? 'write' : 'overwrite',
-        reason: existingContent === null ? 'new artifact' : 'forced overwrite of an unmanaged file',
-    };
-}
-
-/**
- * @param {{
- *   destinationRoot: string,
- *   destinationPath: string,
- *   targetPath: string,
- *   entry: Record<string, any>,
- *   config: Awaited<ReturnType<import('./config.js').resolveConfig>>,
- *   fsImpl: typeof fsp,
- * }} params
- */
-async function createPruneAction({ destinationRoot, destinationPath, targetPath, entry, config, fsImpl }) {
-    const existingContent = await readTextIfExists(targetPath, fsImpl);
-    const localHash = existingContent === null ? null : hashContent(existingContent);
-    const expectedHash = String(entry.lastKnownLocalContentHash ?? '');
-
-    if (existingContent !== null && expectedHash && localHash !== expectedHash && !config.force) {
-        return {
-            kind: 'prune',
-            action: 'conflict',
-            destinationPath,
-            targetPath,
-            entry,
-            localHash,
-            blocked: true,
-            reason: 'local changes differ from the last Rubrkit pull',
-        };
-    }
-
-    return {
-        kind: 'prune',
-        action: 'prune',
-        destinationPath,
-        targetPath,
-        entry,
-        localHash,
-        blocked: false,
-        reason: existingContent === null ? 'tracked file is already missing' : 'remote artifact is no longer selected',
-        destinationRoot,
-    };
-}
-
-/**
- * @param {string} targetPath
- * @param {typeof fsp} fsImpl
- */
-async function readTextIfExists(targetPath, fsImpl) {
-    try {
-        return await fsImpl.readFile(targetPath, 'utf8');
-    } catch (error) {
-        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
-            return null;
-        }
-
-        throw error;
-    }
-}
-
-/**
- * @param {{ plan: Awaited<ReturnType<typeof createPullPlan>>, destinationRoot: string, dryRun: boolean, stdout: NodeJS.WritableStream }} params
- */
-function printPlan({ plan, destinationRoot, dryRun, stdout }) {
-    stdout.write(`${dryRun ? 'Rubrkit pull dry run' : 'Rubrkit pull plan'}\n`);
-    stdout.write(`Destination: ${destinationRoot}\n`);
-    stdout.write(`Agent adapter: ${plan.adapterName}\n`);
-
-    for (const action of plan.actions) {
-        const label = action.blocked ? 'protected' : action.action;
-        let source;
-
-        if (action.kind === 'write') {
-            const writeAction = /** @type {Record<string, any>} */ (action);
-            source = `${writeAction.artifactBundle.name ?? writeAction.artifactBundle.id}/${writeAction.file.path}`;
-        } else {
-            const pruneAction = /** @type {Record<string, any>} */ (action);
-            source = String(pruneAction.entry.artifactPath ?? pruneAction.entry.destinationPath);
-        }
-
-        stdout.write(`- ${label}: ${action.destinationPath} <- ${source}`);
-
-        if (action.reason) {
-            stdout.write(` (${action.reason})`);
-        }
-
-        stdout.write('\n');
-    }
-
-    stdout.write(
-        `Summary: ${plan.summary.writes} write/update, ${plan.summary.skips} skipped, ${plan.summary.prunes} pruned, ${plan.summary.conflicts} protected.\n`,
-    );
-}
-
-/**
- * @param {{
- *   plan: Awaited<ReturnType<typeof createPullPlan>>,
- *   manifest: Awaited<ReturnType<typeof loadManifest>>,
- *   destinationRoot: string,
- *   fsImpl: typeof fsp,
- * }} params
- */
-async function applyPlan({ plan, manifest, destinationRoot, fsImpl }) {
-    let manifestChanged = false;
-    const prunedDestinations = new Set();
-
-    for (const action of plan.actions) {
-        if (action.blocked || action.action === 'skip') {
-            continue;
-        }
-
-        if (action.kind === 'prune') {
-            const pruneAction = /** @type {Record<string, any>} */ (action);
-            await fsImpl.rm(pruneAction.targetPath, { force: true });
-            prunedDestinations.add(pruneAction.destinationPath);
-            manifestChanged = true;
-            continue;
-        }
-
-        const writeAction = /** @type {Record<string, any>} */ (action);
-        await fsImpl.mkdir(path.dirname(writeAction.targetPath), { recursive: true });
-        await fsImpl.writeFile(writeAction.targetPath, writeAction.content, 'utf8');
-        upsertManifestEntry(manifest, {
-            artifactBundleId: writeAction.artifactBundle.id,
-            artifactBundleName: writeAction.artifactBundle.name ?? null,
-            artifactId: writeAction.file.id,
-            artifactPath: normalizeArtifactPath(writeAction.file.path),
-            artifactType: writeAction.file.artifactType ?? null,
-            versionId: writeAction.version.id ?? null,
-            versionNumber: writeAction.version.versionNumber ?? writeAction.file.latestVersionNumber ?? null,
-            contentHash: writeAction.remoteHash,
-            destinationPath: writeAction.destinationPath,
-            agent: writeAction.adapterName,
-            lastPulledAt: new Date().toISOString(),
-            lastKnownLocalContentHash: hashContent(writeAction.content),
-        });
-        manifestChanged = true;
-    }
-
-    if (prunedDestinations.size > 0) {
-        removeManifestEntriesByDestination(manifest, prunedDestinations);
-    }
-
-    if (manifestChanged) {
-        await writeManifest(destinationRoot, manifest, fsImpl);
-    }
-}
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+
+import { RubrkitApiClient } from './api.js';
+import { resolveAgentAdapter } from './adapters.js';
+import { authError, RubrkitCliError } from './errors.js';
+import {
+    findManifestEntry,
+    hashContent,
+    loadManifest,
+    removeManifestEntriesByDestination,
+    upsertManifestEntry,
+    writeManifest,
+} from './manifest.js';
+import { normalizeArtifactPath, relativeToRoot, resolveInsideRoot, slugifyPathSegment } from './pathSafety.js';
+import { promptForPullSelections } from './prompts.js';
+
+/**
+ * @param {{
+ *   config: Awaited<ReturnType<import('./config.js').resolveConfig>>,
+ *   stdin?: NodeJS.ReadableStream,
+ *   stdout?: NodeJS.WritableStream,
+ *   stderr?: NodeJS.WritableStream,
+ *   fetchImpl?: typeof fetch,
+ *   fsImpl?: typeof fsp,
+ *   fsSyncImpl?: Pick<typeof fs, 'existsSync'>,
+ * }} params
+ */
+export async function runPull({
+    config,
+    stdin = process.stdin,
+    stdout = process.stdout,
+    fetchImpl = globalThis.fetch,
+    fsImpl = fsp,
+    fsSyncImpl = fs,
+}) {
+    if (!config.apiKey) {
+        throw authError('Missing Rubrkit API key. Set RUBRKIT_API_KEY or pass --api-key.');
+    }
+
+    const destinationRoot = path.resolve(config.destination);
+    const apiClient = new RubrkitApiClient({
+        apiUrl: config.apiUrl,
+        apiKey: config.apiKey,
+        fetchImpl,
+    });
+    const manifest = await loadManifest(destinationRoot, fsImpl);
+    const bundles = await apiClient.listArtifactBundles({ labels: config.label ?? [] });
+    const selections = await resolveSelections({
+        config,
+        apiClient,
+        bundles,
+        manifest,
+        stdin,
+        stdout,
+    });
+
+    if (selections.length === 0) {
+        stdout.write('No artifacts matched the pull request.\n');
+        return;
+    }
+
+    const hydrated = await hydrateSelections({ apiClient, selections });
+    const plan = await createPullPlan({
+        destinationRoot,
+        items: hydrated,
+        manifest,
+        config,
+        fsImpl,
+        fsSyncImpl,
+    });
+
+    printPlan({ plan, destinationRoot, dryRun: config.dryRun, stdout });
+
+    const conflicts = plan.actions.filter((action) => action.blocked);
+
+    if (conflicts.length > 0 && !config.dryRun) {
+        throw new RubrkitCliError(
+            `Pull stopped because ${conflicts.length} local change${conflicts.length === 1 ? '' : 's'} would be overwritten. Re-run with --force to overwrite.`,
+            { code: 'local_changes_protected' },
+        );
+    }
+
+    if (config.dryRun) {
+        return;
+    }
+
+    await applyPlan({ plan, manifest, destinationRoot, fsImpl });
+
+    stdout.write(
+        `Rubrkit pull complete: ${plan.summary.writes} written, ${plan.summary.skips} skipped, ${plan.summary.prunes} pruned.\n`,
+    );
+}
+
+/**
+ * @param {{
+ *   config: Awaited<ReturnType<import('./config.js').resolveConfig>>,
+ *   apiClient: RubrkitApiClient,
+ *   bundles: Array<Record<string, any>>,
+ *   manifest: Awaited<ReturnType<typeof loadManifest>>,
+ *   stdin: NodeJS.ReadableStream,
+ *   stdout: NodeJS.WritableStream,
+ * }} params
+ */
+async function resolveSelections({ config, apiClient, bundles, manifest, stdin, stdout }) {
+    const fileCache = new Map();
+    const loadFiles = async (bundle) => {
+        if (!fileCache.has(bundle.id)) {
+            fileCache.set(bundle.id, await apiClient.listFiles(bundle.id));
+        }
+
+        return fileCache.get(bundle.id);
+    };
+
+    if (config.updateOnly) {
+        return resolveUpdateOnlySelections({ config, bundles, manifest, loadFiles });
+    }
+
+    if (Array.isArray(config.label) && config.label.length > 0) {
+        if (!config.yes) {
+            await confirmAll({ bundleCount: bundles.length, stdin, stdout });
+        }
+
+        return selectAll({ bundles, loadFiles });
+    }
+
+    if (config.all) {
+        if (!config.yes) {
+            await confirmAll({ bundleCount: bundles.length, stdin, stdout });
+        }
+
+        return selectAll({ bundles, loadFiles });
+    }
+
+    if (config.artifactBundle || config.artifact) {
+        return resolveFlagSelections({ config, bundles, loadFiles });
+    }
+
+    if (config.selector) {
+        return resolveSelectorSelections({ selector: config.selector, yes: config.yes, bundles, loadFiles });
+    }
+
+    if (config.yes) {
+        throw new RubrkitCliError('No selector was provided. Use "all", --artifact-bundle, or --artifact with --yes.', {
+            code: 'selector_required',
+            exitCode: 2,
+        });
+    }
+
+    return promptForPullSelections({ bundles, loadFiles, stdin, stdout });
+}
+
+/**
+ * @param {{ bundleCount: number, stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream }} params
+ */
+async function confirmAll({ bundleCount, stdin, stdout }) {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+
+    try {
+        const answer = await rl.question(`Pull all files from ${bundleCount} artifact bundle${bundleCount === 1 ? '' : 's'}? [y/N] `);
+
+        if (!['y', 'yes'].includes(answer.trim().toLowerCase())) {
+            throw new RubrkitCliError('Pull cancelled.', { code: 'pull_cancelled', exitCode: 2 });
+        }
+    } finally {
+        rl.close();
+    }
+}
+
+/**
+ * @param {{ bundles: Array<Record<string, any>>, loadFiles(bundle: Record<string, any>): Promise<Array<Record<string, any>>> }} params
+ */
+async function selectAll({ bundles, loadFiles }) {
+    const selections = [];
+
+    for (const bundle of bundles) {
+        const files = await loadFiles(bundle);
+
+        for (const file of files) {
+            selections.push({ artifactBundle: bundle, file });
+        }
+    }
+
+    return selections;
+}
+
+/**
+ * @param {{
+ *   config: Awaited<ReturnType<import('./config.js').resolveConfig>>,
+ *   bundles: Array<Record<string, any>>,
+ *   loadFiles(bundle: Record<string, any>): Promise<Array<Record<string, any>>>,
+ * }} params
+ */
+async function resolveFlagSelections({ config, bundles, loadFiles }) {
+    const selectedBundles = config.artifactBundle ? findBundles(bundles, config.artifactBundle) : bundles;
+
+    if (selectedBundles.length === 0) {
+        throw new RubrkitCliError(`No artifact bundle matched "${config.artifactBundle}".`, { code: 'artifact_bundle_not_found' });
+    }
+
+    const selections = [];
+
+    for (const bundle of selectedBundles) {
+        const files = await loadFiles(bundle);
+        const selectedFiles = config.artifact ? findFiles(files, config.artifact) : files;
+
+        for (const file of selectedFiles) {
+            selections.push({ artifactBundle: bundle, file });
+        }
+    }
+
+    if (config.artifact && selections.length === 0) {
+        throw new RubrkitCliError(`No artifact matched "${config.artifact}".`, { code: 'artifact_not_found' });
+    }
+
+    if (config.yes && selectedBundles.length > 1 && config.artifactBundle) {
+        throw new RubrkitCliError(`Artifact bundle selector "${config.artifactBundle}" is ambiguous.`, {
+            code: 'ambiguous_selector',
+            exitCode: 2,
+        });
+    }
+
+    return selections;
+}
+
+/**
+ * @param {{
+ *   selector: string,
+ *   yes: boolean,
+ *   bundles: Array<Record<string, any>>,
+ *   loadFiles(bundle: Record<string, any>): Promise<Array<Record<string, any>>>,
+ * }} params
+ */
+async function resolveSelectorSelections({ selector, yes, bundles, loadFiles }) {
+    const bundleMatches = findBundles(bundles, selector);
+    const fileMatches = [];
+
+    for (const bundle of bundles) {
+        const files = await loadFiles(bundle);
+
+        for (const file of findFiles(files, selector)) {
+            fileMatches.push({ artifactBundle: bundle, file });
+        }
+    }
+
+    const candidateCount = bundleMatches.length + fileMatches.length;
+
+    if (candidateCount === 0) {
+        throw new RubrkitCliError(`No artifact bundle or artifact matched "${selector}".`, { code: 'selector_not_found' });
+    }
+
+    if (candidateCount > 1 && yes) {
+        throw new RubrkitCliError(`Selector "${selector}" is ambiguous. Use --artifact-bundle or --artifact.`, {
+            code: 'ambiguous_selector',
+            exitCode: 2,
+        });
+    }
+
+    if (bundleMatches.length === 1 && fileMatches.length === 0) {
+        const files = await loadFiles(bundleMatches[0]);
+        return files.map((file) => ({ artifactBundle: bundleMatches[0], file }));
+    }
+
+    if (fileMatches.length === 1 && bundleMatches.length === 0) {
+        return fileMatches;
+    }
+
+    throw new RubrkitCliError(`Selector "${selector}" is ambiguous. Use --artifact-bundle or --artifact.`, {
+        code: 'ambiguous_selector',
+        exitCode: 2,
+    });
+}
+
+/**
+ * @param {{
+ *   config: Awaited<ReturnType<import('./config.js').resolveConfig>>,
+ *   bundles: Array<Record<string, any>>,
+ *   manifest: Awaited<ReturnType<typeof loadManifest>>,
+ *   loadFiles(bundle: Record<string, any>): Promise<Array<Record<string, any>>>,
+ * }} params
+ */
+async function resolveUpdateOnlySelections({ config, bundles, manifest, loadFiles }) {
+    const entries = manifest.entries.filter((entry) => matchesEntrySelectors(entry, config));
+    const selections = [];
+
+    for (const entry of entries) {
+        const bundle = bundles.find((candidate) => candidate.id === entry.artifactBundleId);
+
+        if (!bundle) {
+            continue;
+        }
+
+        const files = await loadFiles(bundle);
+        const file = files.find((candidate) => candidate.id === entry.artifactId || candidate.path === entry.artifactPath);
+
+        if (file) {
+            selections.push({ artifactBundle: bundle, file });
+        }
+    }
+
+    return selections;
+}
+
+/**
+ * @param {Record<string, any>} entry
+ * @param {Awaited<ReturnType<import('./config.js').resolveConfig>>} config
+ */
+function matchesEntrySelectors(entry, config) {
+    const selector = config.selector && config.selector !== 'all' ? config.selector : null;
+    const bundleSelector = config.artifactBundle ?? selector;
+    const artifactSelector = config.artifact ?? (bundleSelector === selector ? null : selector);
+    const bundleMatches = !bundleSelector || [entry.artifactBundleId, entry.artifactBundleName].some((value) => matchesSelector(value, bundleSelector));
+    const artifactMatches =
+        !artifactSelector ||
+        [entry.artifactId, entry.artifactPath, path.posix.basename(String(entry.artifactPath ?? ''))].some((value) =>
+            matchesSelector(value, artifactSelector),
+        );
+
+    return bundleMatches && artifactMatches;
+}
+
+/**
+ * @param {Array<Record<string, any>>} bundles
+ * @param {string} selector
+ */
+function findBundles(bundles, selector) {
+    return bundles.filter((bundle) => {
+        const slug = slugifyPathSegment(bundle.name ?? bundle.id);
+
+        return [bundle.id, bundle.name, slug].some((value) => matchesSelector(value, selector));
+    });
+}
+
+/**
+ * @param {Array<Record<string, any>>} files
+ * @param {string} selector
+ */
+function findFiles(files, selector) {
+    return files.filter((file) => {
+        const normalizedPath = normalizeArtifactPath(file.path);
+
+        return [file.id, normalizedPath, path.posix.basename(normalizedPath)].some((value) => matchesSelector(value, selector));
+    });
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} selector
+ */
+function matchesSelector(value, selector) {
+    if (typeof value !== 'string') {
+        return false;
+    }
+
+    return value === selector || value.toLowerCase() === selector.toLowerCase();
+}
+
+/**
+ * @param {{ apiClient: RubrkitApiClient, selections: Array<{ artifactBundle: Record<string, any>, file: Record<string, any> }> }} params
+ */
+async function hydrateSelections({ apiClient, selections }) {
+    const hydrated = [];
+
+    for (const selection of selections) {
+        const detail = await apiClient.getFile(selection.artifactBundle.id, selection.file.id);
+
+        hydrated.push({
+            artifactBundle: selection.artifactBundle,
+            file: detail.file ?? selection.file,
+            version: detail.version ?? {},
+            content: typeof detail.content === 'string' ? detail.content : '',
+        });
+    }
+
+    return hydrated;
+}
+
+/**
+ * @param {{
+ *   destinationRoot: string,
+ *   items: Array<{ artifactBundle: Record<string, any>, file: Record<string, any>, version: Record<string, any>, content: string }>,
+ *   manifest: Awaited<ReturnType<typeof loadManifest>>,
+ *   config: Awaited<ReturnType<import('./config.js').resolveConfig>>,
+ *   fsImpl: typeof fsp,
+ *   fsSyncImpl: Pick<typeof fs, 'existsSync'>,
+ * }} params
+ */
+async function createPullPlan({ destinationRoot, items, manifest, config, fsImpl, fsSyncImpl }) {
+    const adapter = resolveAgentAdapter({
+        root: destinationRoot,
+        requestedAgent: config.agent,
+        fsImpl: fsSyncImpl,
+    });
+    const actions = [];
+    const selectedDestinationPaths = new Set();
+    const selectedBundleIds = new Set(items.map((item) => item.artifactBundle.id));
+
+    for (const item of items) {
+        const placement = adapter.place({
+            artifactBundle: item.artifactBundle,
+            file: item.file,
+            exists(relativePath) {
+                return fsSyncImpl.existsSync(resolveInsideRoot(destinationRoot, relativePath));
+            },
+        });
+        const targetPath = resolveInsideRoot(destinationRoot, placement.destinationPath);
+        const destinationPath = relativeToRoot(destinationRoot, targetPath);
+        selectedDestinationPaths.add(destinationPath);
+
+        actions.push(
+            await createWriteAction({
+                adapterName: adapter.name,
+                destinationPath,
+                targetPath,
+                placementReason: placement.reason,
+                item,
+                manifest,
+                config,
+                fsImpl,
+            }),
+        );
+    }
+
+    if (config.prune) {
+        for (const entry of manifest.entries) {
+            const destinationPath = String(entry.destinationPath ?? '');
+
+            if (!selectedBundleIds.has(entry.artifactBundleId) || selectedDestinationPaths.has(destinationPath)) {
+                continue;
+            }
+
+            const targetPath = resolveInsideRoot(destinationRoot, destinationPath);
+            actions.push(await createPruneAction({ destinationRoot, destinationPath, targetPath, entry, config, fsImpl }));
+        }
+    }
+
+    const summary = {
+        writes: actions.filter((action) => ['write', 'overwrite', 'update'].includes(action.action)).length,
+        skips: actions.filter((action) => action.action === 'skip').length,
+        prunes: actions.filter((action) => action.action === 'prune').length,
+        conflicts: actions.filter((action) => action.blocked).length,
+    };
+
+    return { adapterName: adapter.name, actions, summary };
+}
+
+/**
+ * @param {{
+ *   adapterName: string,
+ *   destinationPath: string,
+ *   targetPath: string,
+ *   placementReason: string,
+ *   item: { artifactBundle: Record<string, any>, file: Record<string, any>, version: Record<string, any>, content: string },
+ *   manifest: Awaited<ReturnType<typeof loadManifest>>,
+ *   config: Awaited<ReturnType<import('./config.js').resolveConfig>>,
+ *   fsImpl: typeof fsp,
+ * }} params
+ */
+async function createWriteAction({ adapterName, destinationPath, targetPath, placementReason, item, manifest, config, fsImpl }) {
+    const existingContent = await readTextIfExists(targetPath, fsImpl);
+    const localHash = existingContent === null ? null : hashContent(existingContent);
+    const remoteHash = item.version.contentHash ?? item.file.contentHash ?? hashContent(item.content);
+    const manifestEntry = findManifestEntry(manifest, {
+        artifactBundleId: item.artifactBundle.id,
+        artifactId: item.file.id,
+        destinationPath,
+    });
+    const base = {
+        kind: 'write',
+        action: 'write',
+        adapterName,
+        destinationPath,
+        targetPath,
+        placementReason,
+        artifactBundle: item.artifactBundle,
+        file: item.file,
+        version: item.version,
+        content: item.content,
+        remoteHash,
+        localHash,
+        manifestEntry,
+        blocked: false,
+        reason: '',
+    };
+
+    if (manifestEntry) {
+        const expectedHash = String(manifestEntry.lastKnownLocalContentHash ?? '');
+
+        if (localHash && expectedHash && localHash !== expectedHash && !config.force) {
+            return {
+                ...base,
+                action: 'conflict',
+                blocked: true,
+                reason: 'local changes differ from the last Rubrkit pull',
+            };
+        }
+
+        if (localHash === remoteHash && manifestEntry.contentHash === remoteHash) {
+            return {
+                ...base,
+                action: 'skip',
+                reason: 'already up to date',
+            };
+        }
+
+        return {
+            ...base,
+            action: existingContent === null ? 'write' : 'update',
+            reason: existingContent === null ? 'tracked file is missing locally' : 'remote artifact changed',
+        };
+    }
+
+    if (config.updateOnly) {
+        return {
+            ...base,
+            action: 'skip',
+            reason: 'not tracked in the local manifest',
+        };
+    }
+
+    if (existingContent !== null && !config.force) {
+        return {
+            ...base,
+            action: 'conflict',
+            blocked: true,
+            reason: 'destination exists and is not managed by Rubrkit',
+        };
+    }
+
+    return {
+        ...base,
+        action: existingContent === null ? 'write' : 'overwrite',
+        reason: existingContent === null ? 'new artifact' : 'forced overwrite of an unmanaged file',
+    };
+}
+
+/**
+ * @param {{
+ *   destinationRoot: string,
+ *   destinationPath: string,
+ *   targetPath: string,
+ *   entry: Record<string, any>,
+ *   config: Awaited<ReturnType<import('./config.js').resolveConfig>>,
+ *   fsImpl: typeof fsp,
+ * }} params
+ */
+async function createPruneAction({ destinationRoot, destinationPath, targetPath, entry, config, fsImpl }) {
+    const existingContent = await readTextIfExists(targetPath, fsImpl);
+    const localHash = existingContent === null ? null : hashContent(existingContent);
+    const expectedHash = String(entry.lastKnownLocalContentHash ?? '');
+
+    if (existingContent !== null && expectedHash && localHash !== expectedHash && !config.force) {
+        return {
+            kind: 'prune',
+            action: 'conflict',
+            destinationPath,
+            targetPath,
+            entry,
+            localHash,
+            blocked: true,
+            reason: 'local changes differ from the last Rubrkit pull',
+        };
+    }
+
+    return {
+        kind: 'prune',
+        action: 'prune',
+        destinationPath,
+        targetPath,
+        entry,
+        localHash,
+        blocked: false,
+        reason: existingContent === null ? 'tracked file is already missing' : 'remote artifact is no longer selected',
+        destinationRoot,
+    };
+}
+
+/**
+ * @param {string} targetPath
+ * @param {typeof fsp} fsImpl
+ */
+async function readTextIfExists(targetPath, fsImpl) {
+    try {
+        return await fsImpl.readFile(targetPath, 'utf8');
+    } catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+            return null;
+        }
+
+        throw error;
+    }
+}
+
+/**
+ * @param {{ plan: Awaited<ReturnType<typeof createPullPlan>>, destinationRoot: string, dryRun: boolean, stdout: NodeJS.WritableStream }} params
+ */
+function printPlan({ plan, destinationRoot, dryRun, stdout }) {
+    stdout.write(`${dryRun ? 'Rubrkit pull dry run' : 'Rubrkit pull plan'}\n`);
+    stdout.write(`Destination: ${destinationRoot}\n`);
+    stdout.write(`Agent adapter: ${plan.adapterName}\n`);
+
+    for (const action of plan.actions) {
+        const label = action.blocked ? 'protected' : action.action;
+        let source;
+
+        if (action.kind === 'write') {
+            const writeAction = /** @type {Record<string, any>} */ (action);
+            source = `${writeAction.artifactBundle.name ?? writeAction.artifactBundle.id}/${writeAction.file.path}`;
+        } else {
+            const pruneAction = /** @type {Record<string, any>} */ (action);
+            source = String(pruneAction.entry.artifactPath ?? pruneAction.entry.destinationPath);
+        }
+
+        stdout.write(`- ${label}: ${action.destinationPath} <- ${source}`);
+
+        if (action.reason) {
+            stdout.write(` (${action.reason})`);
+        }
+
+        stdout.write('\n');
+    }
+
+    stdout.write(
+        `Summary: ${plan.summary.writes} write/update, ${plan.summary.skips} skipped, ${plan.summary.prunes} pruned, ${plan.summary.conflicts} protected.\n`,
+    );
+}
+
+/**
+ * @param {{
+ *   plan: Awaited<ReturnType<typeof createPullPlan>>,
+ *   manifest: Awaited<ReturnType<typeof loadManifest>>,
+ *   destinationRoot: string,
+ *   fsImpl: typeof fsp,
+ * }} params
+ */
+async function applyPlan({ plan, manifest, destinationRoot, fsImpl }) {
+    let manifestChanged = false;
+    const prunedDestinations = new Set();
+
+    for (const action of plan.actions) {
+        if (action.blocked || action.action === 'skip') {
+            continue;
+        }
+
+        if (action.kind === 'prune') {
+            const pruneAction = /** @type {Record<string, any>} */ (action);
+            await fsImpl.rm(pruneAction.targetPath, { force: true });
+            prunedDestinations.add(pruneAction.destinationPath);
+            manifestChanged = true;
+            continue;
+        }
+
+        const writeAction = /** @type {Record<string, any>} */ (action);
+        await fsImpl.mkdir(path.dirname(writeAction.targetPath), { recursive: true });
+        await fsImpl.writeFile(writeAction.targetPath, writeAction.content, 'utf8');
+        upsertManifestEntry(manifest, {
+            artifactBundleId: writeAction.artifactBundle.id,
+            artifactBundleName: writeAction.artifactBundle.name ?? null,
+            artifactId: writeAction.file.id,
+            artifactPath: normalizeArtifactPath(writeAction.file.path),
+            artifactType: writeAction.file.artifactType ?? null,
+            versionId: writeAction.version.id ?? null,
+            versionNumber: writeAction.version.versionNumber ?? writeAction.file.latestVersionNumber ?? null,
+            contentHash: writeAction.remoteHash,
+            destinationPath: writeAction.destinationPath,
+            agent: writeAction.adapterName,
+            lastPulledAt: new Date().toISOString(),
+            lastKnownLocalContentHash: hashContent(writeAction.content),
+        });
+        manifestChanged = true;
+    }
+
+    if (prunedDestinations.size > 0) {
+        removeManifestEntriesByDestination(manifest, prunedDestinations);
+    }
+
+    if (manifestChanged) {
+        await writeManifest(destinationRoot, manifest, fsImpl);
+    }
+}