acker-dacker 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# Acker Dacker
+
+A Bun CLI for making deterministic repository ZIPs for AI handoffs and code review.
+
+## Requirements
+
+- [Bun](https://bun.sh/) 1.0 or newer
+- Git only for `--git-handoff`
+
+## Use it
+
+Run the published CLI without a global install:
+
+```bash
+bunx acker-dacker <repository-path> [options]
+```
+
+Examples:
+
+```bash
+# Privacy-oriented default pack
+bunx acker-dacker ../my-repository
+
+# Include only Markdown and TypeScript files
+bunx acker-dacker ../my-repository --filter "*.md" --filter "*.ts"
+
+# Include an additional local directory
+bunx acker-dacker ../my-repository --include ../shared-fixtures
+
+# Capture the Git worktree, including eligible untracked files
+bunx acker-dacker ../my-repository --git-handoff --output ./handoff.zip
+
+# Create the minimal Rust Stage 3 handoff and a content-free report
+bunx acker-dacker ../codex --git-handoff --profile rust-stage3 \
+  --output ./rust-stage3.zip --report ./rust-stage3.json
+```
+
+If `<repository-path>` is omitted, the current directory is used. Default-mode output is `./<repository-name>-pack.zip` unless `--output` is supplied.
+
+Run `bunx acker-dacker --help` for the current usage text. The options are:
+
+| Option | Description |
+| --- | --- |
+| `--git-handoff` | Use Git's tracked plus eligible-untracked file set and preserve modes and safe symlinks. |
+| `--profile <name>` | Select a Git handoff profile. Currently `rust-stage3`; requires `--git-handoff`. |
+| `--filter, -f <pattern>` | Include only matching paths or file names. Repeatable. |
+| `--include, -i <path>` | Add a local directory or repository dependency in default mode. Repeatable. |
+| `--exclude <path\|glob>` | Exclude a root-relative path or glob in Git handoff mode. Repeatable. |
+| `--output, -o <path>` | Set the ZIP output path. |
+| `--report <path>` | Write a content-free Git handoff JSON report. Requires `--git-handoff`. |
+| `--help, -h` | Show help. |
+
+## Modes and safety
+
+Default mode recursively discovers local `file:` and `link:` package dependencies, follows root and nested `.gitignore` files, and omits common generated output, Xcode build artifacts, and sensitive file names. It also supports explicit `--include` paths.
+
+Git handoff mode asks Git for tracked files and standard-ignore-aware untracked files. Tracked files remain eligible by design; sensitive and generated files are safety-filtered only when untracked. Absolute, escaping, dangling, and cyclic symlinks are rejected. `--exclude`, `--filter`, `--profile`, and `--report` are applied as documented above.
+
+Archives are deterministic: file ordering, ZIP timestamps, and compression choices do not depend on the current clock.
+
+## Development
+
+```bash
+bun install
+bun run test
+bun run typecheck
+bun run check
+bun run build
+```
+
+The CLI entrypoint is `index.ts`. Workflow orchestration lives in `src/cli.ts`; argument parsing is in `src/cli-options.ts`; default discovery and policy are in `src/repository-pack.ts`, `src/gitignore.ts`, and `src/file-policy.ts`; Git handoff selection and staging are in `src/git-handoff-selection.ts` and `src/git-handoff.ts`; deterministic ZIP writing is in `src/zip.ts`.
+
+To inspect the npm package before publishing:
+
+```bash
+npm pack --dry-run
+```
+
+The package exposes the `acker-dacker` bin and intentionally ships only `index.ts` and `src/` as application files, plus npm's standard metadata files.

package/index.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env bun
+import { main } from './src/cli';
+
+try {
+    await main();
+} catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`acker-dacker: ${message}`);
+    process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "acker-dacker",
+	"author": {
+		"name": "Ragaeeb Haq",
+		"url": "https://github.com/ragaeeb"
+	},
+	"bugs": {
+		"url": "https://github.com/ragaeeb/acker-dacker/issues"
+	},
+	"version": "0.1.0",
+	"description": "Create deterministic, privacy-aware repository ZIPs for AI handoffs and code review.",
+	"type": "module",
+	"bin": {
+		"acker-dacker": "index.ts"
+	},
+	"files": [
+		"index.ts",
+		"src"
+	],
+	"scripts": {
+		"build": "bun build ./index.ts --target=bun --outfile ./dist/acker-dacker.js",
+		"check": "bun run typecheck && bun test && bun build ./index.ts --target=bun --outfile /tmp/acker-dacker-check.js",
+		"prepublishOnly": "bun run check",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit"
+	},
+	"engines": {
+		"bun": ">=1.4.0",
+		"node": ">=24.x"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.4.0",
+		"typescript": "^7.0.2"
+	}
+}

package/src/cli-options.ts

@@ -0,0 +1,93 @@
+export type CliOptions = {
+    readonly excludes: readonly string[];
+    readonly filters: readonly string[];
+    readonly gitHandoff: boolean;
+    readonly includes: readonly string[];
+    readonly outputFile: string | null;
+    readonly profile: string | null;
+    readonly reportFile: string | null;
+    readonly showHelp: boolean;
+    readonly targetDir: string;
+};
+
+export const parseCliArgs = (args: readonly string[]): CliOptions => {
+    const excludes: string[] = [];
+    const filters: string[] = [];
+    const includes: string[] = [];
+    let gitHandoff = false;
+    let outputFile: string | null = null;
+    let profile: string | null = null;
+    let reportFile: string | null = null;
+    let showHelp = false;
+    let targetDir = process.cwd();
+
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index]!;
+        if (argument === '--help' || argument === '-h') {
+            showHelp = true;
+        } else if (argument === '--git-handoff') {
+            gitHandoff = true;
+        } else if (argument.startsWith('--profile=')) {
+            profile = argument.slice(10) || null;
+        } else if (argument === '--profile') {
+            index += 1;
+            profile = args[index] ?? null;
+        } else if (argument.startsWith('--exclude=')) {
+            excludes.push(argument.slice(10));
+        } else if (argument === '--exclude') {
+            index += 1;
+            if (args[index]) {
+                excludes.push(args[index]!);
+            }
+        } else if (argument.startsWith('--output=')) {
+            outputFile = argument.slice(9);
+        } else if (argument === '--output' || argument === '-o') {
+            index += 1;
+            outputFile = args[index] ?? null;
+        } else if (argument.startsWith('--include=')) {
+            includes.push(argument.slice(10));
+        } else if (argument === '--include' || argument === '-i') {
+            index += 1;
+            if (args[index]) {
+                includes.push(args[index]!);
+            }
+        } else if (argument.startsWith('--filter=')) {
+            filters.push(argument.slice(9));
+        } else if (argument === '--filter' || argument === '-f') {
+            index += 1;
+            if (args[index]) {
+                filters.push(args[index]!);
+            }
+        } else if (argument.startsWith('--report=')) {
+            reportFile = argument.slice(9);
+        } else if (argument === '--report') {
+            index += 1;
+            reportFile = args[index] ?? null;
+        } else if (!argument.startsWith('-')) {
+            targetDir = argument;
+        }
+    }
+
+    return { excludes, filters, gitHandoff, includes, outputFile, profile, reportFile, showHelp, targetDir };
+};
+
+export const printUsage = (): void => {
+    console.log(`
+Usage: acker-dacker [targetRepoPath] [options]
+
+Options:
+  --git-handoff          Use Git's tracked + eligible-untracked set and preserve modes/symlinks
+  --profile <name>       Select a named Git handoff profile (currently rust-stage3; requires --git-handoff)
+  --filter, -f <pattern> Include ONLY files matching pattern (e.g. *.md, *.ts; can be specified multiple times)
+  --include, -i <path>   Additional folder path or repo name to include (can be specified multiple times)
+  --exclude <path|glob>  Repeatable root-relative exclusion (only with --git-handoff)
+  --output, -o <path>    Output zip file path (default: ./<targetRepoName>-pack.zip)
+  --report <path>        Write a content-free Git handoff JSON report (only with --git-handoff)
+  --help, -h             Show this help message
+
+Examples:
+  acker-dacker ../ushman --filter "*.md"
+  acker-dacker ../ushman --include ../ushman-spector -f "*.md" -f "*.ts"
+  acker-dacker ../kodeguard --output=./kodeguard.zip
+`);
+};

package/src/cli.ts

@@ -0,0 +1,115 @@
+import { mkdtemp, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { parseCliArgs, printUsage } from './cli-options';
+import { runGitHandoff } from './git-handoff';
+import { globToRegex } from './path-patterns';
+import { copyRepositoryFiles, discoverRecursiveRepositories } from './repository-pack';
+import { createZipFile } from './zip';
+
+const resolveTargetDirectory = (targetDir: string): string => {
+    return path.resolve(targetDir.replace(/^~(?=$|\/)/, process.env.HOME ?? ''));
+};
+
+const runDefaultPack = async ({
+    filters,
+    includes,
+    outputFile,
+    targetDir,
+}: {
+    readonly filters: readonly string[];
+    readonly includes: readonly string[];
+    readonly outputFile: string | null;
+    readonly targetDir: string;
+}): Promise<void> => {
+    console.log(`Resolving repositories for target: ${targetDir}`);
+    if (includes.length > 0) {
+        console.log(`Explicit includes specified: ${includes.join(', ')}`);
+    }
+    if (filters.length > 0) {
+        console.log(`File filters applied: ${filters.join(', ')}`);
+    }
+
+    const filterMatchers = filters.map(globToRegex);
+    const repositories = await discoverRecursiveRepositories(targetDir, includes);
+    console.log(`Discovered ${repositories.length} repository dependency closure:`);
+    for (const repository of repositories) {
+        const projectKind = repository.isXcodeProject ? ' [Xcode project]' : '';
+        console.log(
+            `  - ${repository.name}${projectKind} (${repository.path}) -> archive: ${repository.archivePrefix}/`,
+        );
+    }
+
+    const mainRepositoryName = path.basename(targetDir);
+    const resolvedOutputFile = path.resolve(
+        outputFile ?? path.join(process.cwd(), `${mainRepositoryName}-pack.zip`),
+    );
+    const stagingRoot = await mkdtemp(path.join(tmpdir(), 'pack-repo-staging-'));
+
+    try {
+        let totalFiles = 0;
+        let totalUncompressedBytes = 0;
+
+        for (const repository of repositories) {
+            const stats = await copyRepositoryFiles(repository, stagingRoot, filterMatchers);
+            totalFiles += stats.fileCount;
+            totalUncompressedBytes += stats.totalBytes;
+            console.log(
+                `Staged ${repository.name}: ${stats.fileCount} files (${(stats.totalBytes / 1024 / 1024).toFixed(2)} MB)`,
+            );
+        }
+
+        if (totalFiles === 0) {
+            console.warn('\nWarning: No files matched the criteria. Zip file will not be created.');
+            return;
+        }
+
+        console.log(`Creating zip archive at: ${resolvedOutputFile}`);
+        await createZipFile(stagingRoot, resolvedOutputFile);
+
+        const zipStats = await stat(resolvedOutputFile);
+        console.log('\nPack complete!');
+        console.log(`Repositories packaged: ${repositories.length}`);
+        console.log(`Total files:           ${totalFiles}`);
+        console.log(`Uncompressed size:     ${(totalUncompressedBytes / 1024 / 1024).toFixed(2)} MB`);
+        console.log(`Zip archive size:      ${(zipStats.size / 1024 / 1024).toFixed(2)} MB`);
+        console.log(`Output archive:        ${resolvedOutputFile}`);
+    } finally {
+        await rm(stagingRoot, { force: true, recursive: true });
+    }
+};
+
+export const main = async (args: readonly string[] = process.argv.slice(2)): Promise<void> => {
+    const options = parseCliArgs(args);
+    if (options.showHelp) {
+        printUsage();
+        return;
+    }
+
+    const targetDir = resolveTargetDirectory(options.targetDir);
+    if (options.gitHandoff) {
+        if (options.includes.length > 0) {
+            throw new Error('--include is not supported with --git-handoff; Git defines the handoff boundary.');
+        }
+        await runGitHandoff({
+            excludes: options.excludes,
+            filters: options.filters.map(globToRegex),
+            outputFile: options.outputFile,
+            profile: options.profile,
+            reportFile: options.reportFile,
+            targetDir,
+        });
+        return;
+    }
+
+    if (options.excludes.length > 0 || options.profile || options.reportFile) {
+        throw new Error('--exclude, --profile, and --report require --git-handoff.');
+    }
+
+    await runDefaultPack({
+        filters: options.filters,
+        includes: options.includes,
+        outputFile: options.outputFile,
+        targetDir,
+    });
+};

package/src/file-policy.ts

@@ -0,0 +1,121 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+
+const EXCLUDED_DIRECTORY_NAMES = new Set([
+    '.cache',
+    '.claude',
+    '.codex',
+    '.git',
+    '.github',
+    '.idea',
+    '.lab',
+    '.minimax',
+    '.next',
+    '.pnpm-store',
+    '.build',
+    '.swiftpm',
+    '.turbo',
+    '.vite',
+    '.vscode',
+    'bin',
+    'build',
+    'coverage',
+    'dist',
+    'node_modules',
+    'playwright-report',
+    'test-results',
+    'tmp',
+]);
+
+const XCODE_BUILD_DIRECTORY_SUFFIXES = ['.app', '.appex', '.dsym', '.xcarchive', '.xcresult', '.xctest'];
+const XCODE_BUILD_DIRECTORY_NAMES = new Set([
+    'deriveddata',
+    'xcuserdata',
+    'sourcepackages',
+    'index.noindex',
+    'modulecache.noindex',
+]);
+const XCODE_BUILD_FILE_SUFFIXES = ['.ipa', '.xcarchive', '.xcresult', '.xcuserstate'];
+
+const ALLOWED_ENV_FILES = new Set(['.env.example', '.env.sample', '.env.template']);
+
+const EXCLUDED_FILE_NAMES = new Set([
+    '.DS_Store',
+    '.gitignore',
+    '.npmrc',
+    '.pypirc',
+    'LICENSE',
+    'LICENSE.md',
+    'credentials.json',
+    'id_ed25519',
+    'id_rsa',
+    'pnpm-lock.yaml',
+    'release.config.cjs',
+    'release.config.mjs',
+    'service-account.json',
+]);
+
+const EXCLUDED_FILE_SUFFIXES = ['.key', '.keystore', '.log', '.p12', '.pem', '.pfx'];
+const GENERATED_ARCHIVE_SUFFIXES = ['.br', '.gz', '.har', '.tar', '.tgz', '.zip'];
+
+export const detectXcodeProject = async (directory: string): Promise<boolean> => {
+    const entries = await readdir(directory, { withFileTypes: true });
+    return entries.some((entry) => {
+        if (entry.isSymbolicLink()) {
+            return false;
+        }
+        const lowerName = entry.name.toLowerCase();
+        return lowerName.endsWith('.xcodeproj') || lowerName.endsWith('.xcworkspace');
+    });
+};
+
+export const isExcludedDirectory = (directoryName: string, isXcodeProject: boolean): boolean => {
+    const lowerName = directoryName.toLowerCase();
+    if (EXCLUDED_DIRECTORY_NAMES.has(directoryName) || EXCLUDED_DIRECTORY_NAMES.has(lowerName)) {
+        return true;
+    }
+
+    return (
+        isXcodeProject &&
+        (XCODE_BUILD_DIRECTORY_NAMES.has(lowerName) ||
+            XCODE_BUILD_DIRECTORY_SUFFIXES.some((suffix) => lowerName.endsWith(suffix)))
+    );
+};
+
+export const isExcludedFile = (fileName: string, isXcodeProject: boolean): boolean => {
+    const lowerName = fileName.toLowerCase();
+    if (EXCLUDED_FILE_NAMES.has(fileName) || EXCLUDED_FILE_NAMES.has(lowerName)) {
+        return true;
+    }
+    if ((lowerName === '.env' || lowerName.startsWith('.env.')) && !ALLOWED_ENV_FILES.has(lowerName)) {
+        return true;
+    }
+    if (EXCLUDED_FILE_SUFFIXES.some((suffix) => lowerName.endsWith(suffix))) {
+        return true;
+    }
+    if (GENERATED_ARCHIVE_SUFFIXES.some((suffix) => lowerName.endsWith(suffix))) {
+        return true;
+    }
+    return isXcodeProject && XCODE_BUILD_FILE_SUFFIXES.some((suffix) => lowerName.endsWith(suffix));
+};
+
+export const isSensitiveUntrackedPath = (relativePath: string): boolean => {
+    const lowerName = path.posix.basename(relativePath).toLowerCase();
+    const sensitiveNames = new Set(['credentials.json', 'id_ed25519', 'id_rsa', 'service-account.json']);
+    if (sensitiveNames.has(lowerName)) {
+        return true;
+    }
+    if (lowerName === '.env' || lowerName.startsWith('.env.')) {
+        return !ALLOWED_ENV_FILES.has(lowerName);
+    }
+    return EXCLUDED_FILE_SUFFIXES.some((suffix) => lowerName.endsWith(suffix));
+};
+
+export const isUntrackedSafetyExcludedPath = (relativePath: string, isXcodeProject: boolean): boolean => {
+    const segments = relativePath.split('/');
+    const directorySegments = segments.slice(0, -1);
+    if (directorySegments.some((segment) => isExcludedDirectory(segment, isXcodeProject))) {
+        return true;
+    }
+    return isExcludedFile(path.posix.basename(relativePath), isXcodeProject);
+};