all-hands-cli 0.1.0

package/src/lib/manifest.ts

@@ -0,0 +1,121 @@
+import { readFileSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+import { minimatch, Minimatch } from 'minimatch';
+import { GitignoreFilter } from './gitignore.js';
+
+interface InternalData {
+  internal?: string[];
+  initOnly?: string[];
+}
+
+const INTERNAL_FILENAME = '.internal.json';
+
+export class Manifest {
+  private allhandsRoot: string;
+  private internalPath: string;
+  private data: InternalData;
+  private gitignoreFilter: GitignoreFilter;
+  private initOnlyMatchers: { matcher: Minimatch; negated: boolean }[];
+
+  constructor(allhandsRoot: string) {
+    this.allhandsRoot = allhandsRoot;
+    this.internalPath = join(allhandsRoot, INTERNAL_FILENAME);
+    this.data = this.load();
+    this.gitignoreFilter = new GitignoreFilter(allhandsRoot);
+    this.initOnlyMatchers = this.initOnlyPatterns.map(p => {
+      const negated = p.startsWith('!');
+      const pattern = negated ? p.slice(1) : p;
+      return { matcher: new Minimatch(pattern, { dot: true }), negated };
+    });
+  }
+
+  private load(): InternalData {
+    if (!existsSync(this.internalPath)) {
+      throw new Error(`Internal config not found: ${this.internalPath}`);
+    }
+    const content = readFileSync(this.internalPath, 'utf-8');
+    return JSON.parse(content);
+  }
+
+  get internalPatterns(): string[] {
+    return this.data.internal || [];
+  }
+
+  get initOnlyPatterns(): string[] {
+    return this.data.initOnly || [];
+  }
+
+  /**
+   * Check if a file is marked as internal (should not be distributed).
+   */
+  isInternal(path: string): boolean {
+    return this.internalPatterns.some(pattern => minimatch(path, pattern, { dot: true }));
+  }
+
+  /**
+   * Check if a file is init-only using last-match-wins semantics with negation support.
+   * Patterns starting with `!` exempt matching files from being init-only.
+   */
+  isInitOnly(path: string): boolean {
+    let initOnly = false;
+    for (const { matcher, negated } of this.initOnlyMatchers) {
+      if (matcher.match(path)) {
+        initOnly = !negated;
+      }
+    }
+    return initOnly;
+  }
+
+  /**
+   * Check if a file is gitignored.
+   */
+  isGitignored(path: string): boolean {
+    return this.gitignoreFilter.isIgnored(path);
+  }
+
+  /**
+   * Check if a file should be distributed.
+   * A file is distributable if it's NOT internal AND NOT gitignored.
+   */
+  isDistributable(path: string): boolean {
+    return !this.isInternal(path) && !this.isGitignored(path);
+  }
+
+  /**
+   * Get all distributable files from the allhands root.
+   * Returns files that are NOT internal AND NOT gitignored.
+   */
+  getDistributableFiles(): Set<string> {
+    const allFiles = this.gitignoreFilter.getNonIgnoredFiles();
+    const filtered = new Set<string>();
+
+    for (const file of allFiles) {
+      if (!this.isInternal(file)) {
+        filtered.add(file);
+      }
+    }
+
+    return filtered;
+  }
+}
+
+/**
+ * Compare two files byte-by-byte.
+ */
+export function filesAreDifferent(file1: string, file2: string): boolean {
+  if (!existsSync(file1) || !existsSync(file2)) {
+    return true;
+  }
+
+  const stat1 = statSync(file1);
+  const stat2 = statSync(file2);
+
+  if (stat1.size !== stat2.size) {
+    return true;
+  }
+
+  const content1 = readFileSync(file1);
+  const content2 = readFileSync(file2);
+
+  return !content1.equals(content2);
+}

package/src/lib/marker-sync.ts

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+
+/**
+ * Ensure a line exists somewhere in a file.
+ * If file doesn't exist, create it with just that line.
+ * Appends to end of file if line doesn't already exist.
+ * Returns true if changes were made.
+ */
+export function ensureLineInFile(filePath: string, line: string, verbose: boolean = false): boolean {
+  let content = '';
+  let existed = false;
+
+  if (existsSync(filePath)) {
+    content = readFileSync(filePath, 'utf-8');
+    existed = true;
+
+    // Already has the line?
+    if (content.includes(line)) {
+      if (verbose) console.log(`  ${filePath} already contains: ${line}`);
+      return false;
+    }
+  }
+
+  // Append the line
+  const lineWithNewline = line + '\n';
+
+  if (existed && content.trim()) {
+    // Ensure newline separation before appending
+    const separator = content.endsWith('\n') ? '' : '\n';
+    content = content + separator + lineWithNewline;
+  } else {
+    content = lineWithNewline;
+  }
+
+  writeFileSync(filePath, content);
+  if (verbose) console.log(existed ? `  Updated ${filePath}` : `  Created ${filePath}`);
+
+  return true;
+}

package/src/lib/paths.ts

@@ -0,0 +1,38 @@
+import { existsSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+export const UPSTREAM_REPO = 'kalem-edlin/all-hands';
+export const UPSTREAM_OWNER = 'kalem-edlin';
+
+export function getAllhandsRoot(): string {
+  // 1. Check ALLHANDS_PATH env var (for local dev testing)
+  const envPath = process.env.ALLHANDS_PATH;
+  if (envPath) {
+    const resolved = resolve(envPath);
+    if (existsSync(resolved) && existsSync(resolve(resolved, '.internal.json'))) {
+      return resolved;
+    }
+  }
+
+  // 2. Fallback: package location (npx usage)
+  // When bundled with esbuild, this resolves to bin/cli.js
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+
+  // bin/cli.js -> package root (go up one level from bin/)
+  let packageRoot = resolve(__dirname, '..');
+  if (existsSync(resolve(packageRoot, '.internal.json'))) {
+    return packageRoot;
+  }
+
+  // Try going up two levels (in case of dist/lib/paths.js structure)
+  packageRoot = resolve(__dirname, '../..');
+  if (existsSync(resolve(packageRoot, '.internal.json'))) {
+    return packageRoot;
+  }
+
+  throw new Error(
+    'Could not locate allhands package. Ensure you are running via npx or set ALLHANDS_PATH for local dev.'
+  );
+}

package/src/lib/target-lines.ts

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { getAllhandsRoot } from './paths.js';
+import { ensureLineInFile } from './marker-sync.js';
+
+export interface TargetLinesConfig {
+  [filename: string]: string[];
+}
+
+/**
+ * Load the target-lines.json config from the allhands root.
+ */
+export function loadTargetLines(): TargetLinesConfig {
+  const configPath = join(getAllhandsRoot(), 'target-lines.json');
+  const content = readFileSync(configPath, 'utf-8');
+  return JSON.parse(content) as TargetLinesConfig;
+}
+
+/**
+ * Ensure all lines from target-lines.json exist in the target files.
+ * Lines are appended if they don't already exist.
+ *
+ * Special handling for .tldrignore:
+ * - First copies target's ORIGINAL .gitignore as base (hard replace)
+ * - Then appends target-lines
+ *
+ * Returns true if any changes were made.
+ */
+export function ensureTargetLines(targetRoot: string, verbose: boolean = false): boolean {
+  const config = loadTargetLines();
+  let anyChanged = false;
+
+  // Capture original .gitignore content BEFORE any modifications
+  const gitignorePath = join(targetRoot, '.gitignore');
+  const originalGitignore = existsSync(gitignorePath)
+    ? readFileSync(gitignorePath, 'utf-8')
+    : '';
+
+  for (const [filename, lines] of Object.entries(config)) {
+    const targetPath = join(targetRoot, filename);
+
+    if (verbose) console.log(`Ensuring ${filename} has required lines...`);
+
+    // Special handling for .tldrignore - hard replace with original .gitignore content first
+    if (filename === '.tldrignore') {
+      if (verbose && originalGitignore) {
+        console.log('  Copying original .gitignore content to .tldrignore');
+      }
+      let baseContent = originalGitignore;
+      if (baseContent && !baseContent.endsWith('\n')) {
+        baseContent += '\n';
+      }
+      writeFileSync(targetPath, baseContent);
+      anyChanged = true;
+    }
+
+    for (const line of lines) {
+      const updated = ensureLineInFile(targetPath, line, verbose);
+      if (updated) {
+        anyChanged = true;
+      }
+    }
+  }
+
+  return anyChanged;
+}

package/src/lib/ui.ts

@@ -0,0 +1,78 @@
+import { existsSync, readdirSync } from 'fs';
+import { basename, dirname, extname, join } from 'path';
+import * as readline from 'readline';
+
+export type ConflictResolution = 'backup' | 'overwrite' | 'cancel';
+
+export async function askQuestion(question: string): Promise<string> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+export async function confirm(message: string): Promise<boolean> {
+  const answer = await askQuestion(`${message} [y/N]: `);
+  return answer.toLowerCase() === 'y';
+}
+
+export async function askConflictResolution(conflicts: string[]): Promise<ConflictResolution> {
+  console.log(`\n${'!'.repeat(60)}`);
+  console.log('CONFLICTS DETECTED - The following files differ from source:');
+  console.log(`${'!'.repeat(60)}`);
+  for (const f of conflicts.sort()) {
+    console.log(`  → ${f}`);
+  }
+  console.log();
+  console.log('How would you like to handle these conflicts?');
+  console.log('  [b] Create backups (file.backup_N.ext) and overwrite');
+  console.log('  [o] Overwrite all (lose local changes)');
+  console.log('  [c] Cancel (make no changes)');
+  console.log();
+
+  while (true) {
+    const answer = await askQuestion('Choice [b/o/c]: ');
+    switch (answer.toLowerCase()) {
+      case 'b':
+        return 'backup';
+      case 'o':
+        return 'overwrite';
+      case 'c':
+        return 'cancel';
+      default:
+        console.log('Please enter b, o, or c');
+    }
+  }
+}
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function getNextBackupPath(filePath: string): string {
+  const dir = dirname(filePath);
+  const ext = extname(filePath);
+  const base = basename(filePath, ext);
+
+  let n = 1;
+  if (existsSync(dir)) {
+    const files = readdirSync(dir);
+    const backupPattern = new RegExp(`^${escapeRegex(base)}\\.backup_(\\d+)${escapeRegex(ext)}$`);
+    for (const file of files) {
+      const match = file.match(backupPattern);
+      if (match) {
+        const num = parseInt(match[1], 10);
+        if (num >= n) n = num + 1;
+      }
+    }
+  }
+
+  return join(dir, `${base}.backup_${n}${ext}`);
+}

package/src/sync-cli.ts

@@ -0,0 +1,120 @@
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { cmdSync } from './commands/sync.js';
+import { cmdPullManifest } from './commands/pull-manifest.js';
+import { cmdPush } from './commands/push.js';
+import { checkGitInstalled } from './lib/git.js';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+const VERSION = pkg.version;
+
+// Sync command handler for reuse
+const syncHandler = async (argv: { target?: string; yes?: boolean; init?: boolean }) => {
+  const code = await cmdSync(argv.target || '.', argv.yes || false, argv.init || false);
+  process.exit(code);
+};
+
+// Sync command builder for reuse
+const syncBuilder = (yargs: yargs.Argv) => {
+  return yargs
+    .positional('target', {
+      describe: 'Target repository path (defaults to current directory)',
+      type: 'string',
+      default: '.',
+    })
+    .option('yes', {
+      alias: 'y',
+      type: 'boolean',
+      describe: 'Skip confirmation prompts',
+      default: false,
+    })
+    .option('init', {
+      type: 'boolean',
+      describe: 'Include init-only files (for first-time setup)',
+      default: false,
+    });
+};
+
+async function main() {
+  // Check dependencies
+  if (!checkGitInstalled()) {
+    console.error('Error: git is not installed. Please install git first.');
+    process.exit(1);
+  }
+
+  const argv = await yargs(hideBin(process.argv))
+    .scriptName('all-hands')
+    .version(VERSION)
+    .usage('$0 <command> [options]')
+    .command(
+      'sync [target]',
+      'Initialize or update allhands in target repo',
+      syncBuilder,
+      syncHandler
+    )
+    .command(
+      'pull-manifest',
+      'Create sync config for push customization',
+      () => {},
+      async () => {
+        const code = await cmdPullManifest();
+        process.exit(code);
+      }
+    )
+    .command(
+      'push',
+      'Create PR to upstream with local changes',
+      (yargs) => {
+        return yargs
+          .option('include', {
+            alias: 'i',
+            type: 'array',
+            describe: 'Additional files/patterns to include',
+            default: [],
+          })
+          .option('exclude', {
+            alias: 'e',
+            type: 'array',
+            describe: 'Files/patterns to exclude',
+            default: [],
+          })
+          .option('dry-run', {
+            type: 'boolean',
+            describe: 'Preview without creating PR',
+            default: false,
+          })
+          .option('title', {
+            alias: 't',
+            type: 'string',
+            describe: 'PR title (skips prompt)',
+          })
+          .option('body', {
+            alias: 'b',
+            type: 'string',
+            describe: 'PR body (skips prompt)',
+          });
+      },
+      async (argv) => {
+        const code = await cmdPush(
+          argv.include as string[],
+          argv.exclude as string[],
+          argv.dryRun as boolean,
+          argv.title as string | undefined,
+          argv.body as string | undefined
+        );
+        process.exit(code);
+      }
+    )
+    .demandCommand(1, 'Please specify a command')
+    .strict()
+    .help()
+    .alias('h', 'help')
+    .parse();
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/target-lines.json

@@ -0,0 +1,23 @@
+{
+  "CLAUDE.md": [
+    "@.allhands/flows/CORE.md"
+  ],
+  ".gitignore": [
+    ".planning/",
+    ".env.ai",
+    ".tldr/*",
+    "!.tldr/config.json",
+    ".reposearch/",
+    ".allhands-*.backup/",
+    ".claude-*.backup/",
+    ".allhands/harness/.cache/",
+    "test_plan.md",
+    "problems.md"
+  ],
+  ".tldrignore": [
+    ".reposearch/",
+    ".planning/",
+    "docs/",
+    ".allhands/"
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "bin"]
+}