claskit 1.0.0

package/README.md

@@ -0,0 +1,133 @@
+# claskit
+
+Autonomous Claude Code task runner. Write task specs as Markdown, run `claskit`, watch Claude implement them.
+
+```
+  ┌──────────────────────────────────────────────────────────────────┐
+  │                                                                  │
+  │   .claude/tasks/todo/           .claude/tasks/done/             │
+  │   ┌──────────────────┐          ┌──────────────────┐            │
+  │   │  feature-a.md    │          │  feature-a.md    │            │
+  │   │  feature-b.md    │          │                  │            │
+  │   └────────┬─────────┘          └────────▲─────────┘            │
+  │            │                             │                      │
+  │            ▼                             │                      │
+  │      ┌───────────┐                       │                      │
+  │      │  claskit  │                       │                      │
+  │      └─────┬─────┘                       │                      │
+  │            │                             │                      │
+  │     ┌──────┴──────┐                      │                      │
+  │     │             │                      │                      │
+  │  --now       --schedule              implements                 │
+  │     │        HH:MM ⏳                    │                      │
+  │     │             │                      │                      │
+  │     └──────┬───────┘                     │                      │
+  │            ▼                             │                      │
+  │   claude --dangerously-skip-permissions  │                      │
+  │   reads spec → verifies → ──────────────┘                       │
+  │                                                                  │
+  └──────────────────────────────────────────────────────────────────┘
+```
+
+## Requirements
+
+- Node.js 18+
+- [Claude Code CLI](https://claude.ai/code) installed and authenticated
+
+## Install
+
+```bash
+pnpm add -g claskit
+```
+
+## Quick start
+
+```bash
+pnpm add -g claskit
+```
+
+```bash
+claskit
+```
+
+claskit detects if the project is not set up and walks you through initialization interactively.
+
+## Usage
+
+```
+claskit [flag]
+```
+
+| Flag | What it does |
+|------|-------------|
+| _(none)_ | Interactive menu: pick tasks, choose when to run |
+| `--init` | Set up `.claude/tasks/` folder structure in current project |
+| `--now` | Skip menu, run immediately (still shows task picker + confirm) |
+| `--test` | Create 2 sample task files in `todo/` to test the runner |
+| `--clean-test` | Remove all test-generated files |
+
+### Interactive menu options
+
+- **Now** — pick tasks and launch immediately
+- **Schedule (HH:MM)** — live countdown until target time, then launch
+- **Exit**
+
+### Task picker
+
+When 2+ tasks are queued, claskit asks which to run:
+
+```
+Select tasks:
+  Enter numbers separated by commas, or "all"
+  [all]: 1,3
+```
+
+## How it works
+
+1. Claude reads each selected `.md` spec
+2. Decides execution order based on dependencies noted in specs
+3. Implements each task fully
+4. Verifies acceptance criteria
+5. Moves the spec from `todo/` to `done/` on success
+6. Stops and reports if anything fails
+
+Claude runs with `--dangerously-skip-permissions` — it will read, write, and execute commands without prompting. Only use in projects you trust.
+
+## Task spec format
+
+```markdown
+# Feature Title
+
+## Task
+
+What needs to be built.
+
+## Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Files Affected
+
+| File | Change |
+|------|--------|
+| `src/foo.ts` | New component |
+
+## Notes
+
+Dependencies, order hints, constraints.
+```
+
+Save as `.claude/tasks/todo/my-feature.md`.
+
+## Project integration
+
+```bash
+npm pkg set scripts.claskit="claskit"
+```
+
+Then run with `npm run claskit` / `pnpm claskit` / `yarn claskit`.
+
+## License
+
+MIT

package/bin/claskit.js

@@ -0,0 +1,523 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { spawn } = require('child_process');
+
+// ANSI colors
+const C = {
+  red:    '\x1b[31m',
+  green:  '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan:   '\x1b[36m',
+  bold:   '\x1b[1m',
+  dim:    '\x1b[2m',
+  reset:  '\x1b[0m',
+};
+
+const { name, version } = JSON.parse(
+  fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
+);
+
+const TODO_DIR = '.claude/tasks/todo';
+const DONE_DIR = '.claude/tasks/done';
+const TASKS_DIR = '.claude/tasks';
+const PROJECT_NAME = path.basename(process.cwd());
+
+const TASKS_README = `# .claude/tasks
+
+This folder is managed by [claskit](https://github.com/phucbm/claskit) — an autonomous Claude Code task runner.
+
+## How it works
+
+Each \`.md\` file in \`todo/\` is a task spec. When you run \`claskit\`, Claude reads the specs,
+implements them in order, then moves each file to \`done/\` on success.
+
+## Folder structure
+
+\`\`\`
+.claude/tasks/
+  todo/         ← task specs waiting to be implemented
+  done/         ← completed task specs (moved here by claskit after success)
+  README.md     ← this file
+\`\`\`
+
+## Task spec format
+
+Each \`.md\` file should contain:
+- A \`# Title\` heading
+- **Task** section: what to implement
+- **Acceptance Criteria** section: checklist Claude verifies before marking done
+- **Files Affected** section (optional): which files will change
+- **Notes** section (optional): dependencies, order hints, constraints
+
+## For AI assistants reading this
+
+If you see \`.md\` files in \`todo/\`, they are pending implementation specs.
+Do not modify them unless asked. Do not move them to \`done/\` manually.
+claskit handles the lifecycle: read spec → implement → verify → move to done.
+`;
+
+function runInit() {
+  const readmePath = path.join(TASKS_DIR, 'README.md');
+  const alreadyExists = fs.existsSync(TODO_DIR) && fs.existsSync(DONE_DIR);
+
+  fs.mkdirSync(TODO_DIR, { recursive: true });
+  fs.mkdirSync(DONE_DIR, { recursive: true });
+  fs.writeFileSync(readmePath, TASKS_README);
+
+  if (alreadyExists) {
+    console.log(`${C.yellow}Already initialized.${C.reset} Updated README.md.`);
+  } else {
+    console.log(`${C.green}Initialized claskit for ${C.bold}${PROJECT_NAME}${C.reset}`);
+    console.log(`  ${C.dim}Created: ${TODO_DIR}/${C.reset}`);
+    console.log(`  ${C.dim}Created: ${DONE_DIR}/${C.reset}`);
+    console.log(`  ${C.dim}Created: ${TASKS_DIR}/README.md${C.reset}`);
+    console.log('');
+    console.log(`Next: add task specs to ${C.cyan}${TODO_DIR}/${C.reset}`);
+    console.log(`Then run: ${C.cyan}claskit --now${C.reset}`);
+    console.log('');
+    console.log(`${C.dim}To try with sample tasks: claskit --test${C.reset}`);
+  }
+}
+
+const TEST_TASK_1 = `# claskit Test Task 1: Create output file
+
+**Status:** Planned — auto-generated by claskit --test
+
+## Task
+
+Create the file \`.claude/tasks/claskit-test-1.txt\` with this exact content:
+
+\`\`\`
+claskit test task 1 complete
+\`\`\`
+
+## Acceptance Criteria
+
+- [ ] File \`.claude/tasks/claskit-test-1.txt\` exists
+- [ ] File contains "claskit test task 1 complete"
+
+## Notes
+
+Do NOT run any build or lint commands. Just create the file.
+This task must complete before task 2 runs (task 2 reads this file).
+`;
+
+const TEST_TASK_2 = `# claskit Test Task 2: Chain verification
+
+**Status:** Planned — auto-generated by claskit --test
+
+## Task
+
+Read \`.claude/tasks/claskit-test-1.txt\` and confirm it contains "claskit test task 1 complete".
+Then create \`.claude/tasks/claskit-test-2.txt\` with this exact content:
+
+\`\`\`
+claskit test task 2 complete
+task 1 output confirmed
+\`\`\`
+
+## Acceptance Criteria
+
+- [ ] \`.claude/tasks/claskit-test-1.txt\` exists and contains expected text (from task 1)
+- [ ] \`.claude/tasks/claskit-test-2.txt\` created with correct content
+
+## Notes
+
+Do NOT run any build or lint commands. Just read task 1 output and create task 2 file.
+Depends on: claskit-test-task-1.md
+`;
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+function pad(str, len) {
+  const s = String(str);
+  return s.length >= len ? s : s + ' '.repeat(len - s.length);
+}
+
+function box(...lines) {
+  const width = 44;
+  const inner = width - 2;
+  const top    = `╔${'═'.repeat(inner)}╗`;
+  const bottom = `╚${'═'.repeat(inner)}╝`;
+  const rows = lines.map(l => `║  ${pad(l, inner - 2)}║`);
+  return [top, ...rows, bottom].join('\n');
+}
+
+function taskTitle(filepath) {
+  try {
+    const content = fs.readFileSync(filepath, 'utf8');
+    const m = content.match(/^#\s+(.+)/m);
+    return m ? m[1].trim() : path.basename(filepath, '.md');
+  } catch {
+    return path.basename(filepath, '.md');
+  }
+}
+
+function fmtDuration(secs) {
+  const h = Math.floor(secs / 3600);
+  const m = Math.floor((secs % 3600) / 60);
+  const s = secs % 60;
+  if (h > 0) return `${h}h ${String(m).padStart(2,'0')}m ${String(s).padStart(2,'0')}s`;
+  if (m > 0) return `${m}m ${String(s).padStart(2,'0')}s`;
+  return `${s}s`;
+}
+
+// ─── countdown ──────────────────────────────────────────────────────────────
+
+function countdown(totalSecs, label) {
+  return new Promise((resolve) => {
+    let remaining = totalSecs;
+
+    const tick = () => {
+      process.stdout.write(
+        `\r  ${C.yellow}⏳${C.reset} ${label} — ${C.bold}${fmtDuration(remaining)}${C.reset} remaining   `
+      );
+    };
+
+    tick();
+    const timer = setInterval(() => {
+      remaining--;
+      if (remaining <= 0) {
+        clearInterval(timer);
+        process.stdout.write('\r' + ' '.repeat(60) + '\r');
+        resolve();
+      } else {
+        tick();
+      }
+    }, 1000);
+
+    process.on('SIGINT', () => {
+      clearInterval(timer);
+      process.stdout.write('\r' + ' '.repeat(60) + '\r');
+      console.log(`\n${C.red}Cancelled.${C.reset}`);
+      exit(0);
+    });
+  });
+}
+
+// ─── readline prompt helpers ─────────────────────────────────────────────────
+// Single rl instance with an event-driven queue so piped stdin lines
+// are buffered and consumed in order — even when lines arrive before ask() registers.
+
+const _lineQueue = [];
+let _lineWaiter = null;
+let _rl = null;
+
+function initRL() {
+  if (_rl) return;
+  _rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+  _rl.on('line', line => {
+    const trimmed = line.trim();
+    if (_lineWaiter) {
+      const resolve = _lineWaiter;
+      _lineWaiter = null;
+      resolve(trimmed);
+    } else {
+      _lineQueue.push(trimmed);
+    }
+  });
+}
+
+function closeRL() {
+  if (_rl) { _rl.close(); _rl = null; }
+}
+
+function exit(code = 0) {
+  closeRL();
+  process.exit(code);
+}
+
+function ask(question) {
+  initRL();
+  process.stdout.write(question);
+  return new Promise(resolve => {
+    if (_lineQueue.length > 0) {
+      const line = _lineQueue.shift();
+      process.stdout.write(line + '\n');
+      resolve(line);
+    } else {
+      _lineWaiter = resolve;
+    }
+  });
+}
+
+function menu(options) {
+  options.forEach((opt, i) => {
+    console.log(`  ${C.cyan}[${i + 1}]${C.reset} ${opt}`);
+  });
+  return ask(`\n${C.bold}>${C.reset} `);
+}
+
+// ─── launch ──────────────────────────────────────────────────────────────────
+
+async function pickTasks(tasks) {
+  if (tasks.length === 1) return tasks; // nothing to pick
+
+  console.log(`${C.bold}Select tasks:${C.reset}`);
+  console.log(`  ${C.dim}Enter numbers separated by commas, or "all"${C.reset}`);
+  const ans = await ask(`  ${C.dim}[all]${C.reset}: `);
+  const input = ans.trim().toLowerCase();
+
+  if (!input || input === 'all') return tasks;
+
+  const indices = input.split(',').map(s => parseInt(s.trim(), 10) - 1);
+  const selected = indices.filter(i => i >= 0 && i < tasks.length).map(i => tasks[i]);
+
+  if (selected.length === 0) {
+    console.log(`${C.red}No valid tasks selected.${C.reset}`);
+    exit(1);
+  }
+
+  console.log('');
+  console.log(`${C.dim}Running ${selected.length} of ${tasks.length} task(s):${C.reset}`);
+  selected.forEach((f, i) => console.log(`  ${C.cyan}${i + 1}.${C.reset} ${taskTitle(f)}`));
+  return selected;
+}
+
+function buildPrompt(selectedTasks) {
+  const fileList = selectedTasks.map(f => `- ${f.replace(/\\/g, '/')}`).join('\n');
+  return `You are an autonomous task runner for this project.
+
+Your job:
+1. Read ONLY the following task files (ignore other files in .claude/tasks/todo/):
+${fileList}
+2. Analyze each spec and decide the best execution order based on dependencies, complexity, and notes in each file
+3. Tell me the order you chose and why (briefly)
+4. For each task in order:
+   a. Implement it fully according to the spec
+   b. Verify all acceptance criteria listed in the spec are met
+   c. Run the project's build/lint command (check package.json for the right command)
+   d. If build/lint passes → move the .md file from .claude/tasks/todo/ to .claude/tasks/done/
+   e. If something fails → stop, report clearly what failed and why, do not proceed to next task
+5. After all tasks are done, print a summary: what was completed, what was skipped, any issues
+
+Do not ask for confirmation between tasks. Work autonomously until your assigned tasks are done or a blocker is hit.`;
+}
+
+async function confirmLaunch(count) {
+  console.log('');
+  console.log(`  ${C.bold}Ready to run ${count} task(s) autonomously.${C.reset}`);
+  console.log('');
+  console.log(`  ${C.yellow}${C.bold}⚠  WARNING: --dangerously-skip-permissions${C.reset}`);
+  console.log(`  ${C.yellow}Claude will read, write, and run commands WITHOUT asking.${C.reset}`);
+  console.log(`  ${C.yellow}Only use this in a project you trust and have backed up.${C.reset}`);
+  console.log('');
+  const ans = await ask(`  Confirm? ${C.dim}[y/N]${C.reset}: `);
+  return ans.toLowerCase() === 'y';
+}
+
+function launchClaude(prompt, label) {
+  console.log('');
+  console.log(`  ${C.green}${C.bold}Launching Claude Code${label ? ` — ${label}` : ''}${C.reset}`);
+  console.log(`  ${C.dim}Prompt: "${prompt.split('\n')[0]}${prompt.includes('\n') ? '...' : ''}"${C.reset}`);
+  console.log(`\n${'─'.repeat(50)}\n`);
+
+  // Pipe prompt via stdin so Claude runs interactively (tool calls visible)
+  const bin = process.platform === 'win32' ? 'claude.cmd' : 'claude';
+  const child = spawn(bin, ['--dangerously-skip-permissions'], {
+    stdio: ['pipe', 'inherit', 'inherit'],
+    shell: false,
+  });
+
+  child.stdin.write(prompt + '\n');
+  child.stdin.end();
+
+  child.on('exit', code => {
+    console.log(`\n${'─'.repeat(50)}`);
+    if (code !== 0) {
+      console.log(`${C.red}Claude exited with code ${code}${C.reset}`);
+      process.exit(code);
+    } else {
+      console.log(`${C.green}Claude finished successfully.${C.reset}`);
+    }
+  });
+}
+
+async function launchReal(tasks) {
+  const selected = await pickTasks(tasks);
+  const confirmed = await confirmLaunch(selected.length);
+  if (!confirmed) {
+    console.log(`\n${C.dim}Aborted.${C.reset}`);
+    exit(0);
+  }
+  launchClaude(buildPrompt(selected), 'autonomous mode');
+}
+
+// ─── schedule ────────────────────────────────────────────────────────────────
+
+async function scheduleRun(tasks) {
+  const selected = await pickTasks(tasks);
+  const input = await ask(`  Enter time ${C.dim}(HH:MM, 24h)${C.reset}: `);
+  if (!/^([01]\d|2[0-3]):[0-5]\d$/.test(input)) {
+    console.log(`${C.red}Invalid format. Use HH:MM (e.g. 22:30)${C.reset}`);
+    exit(1);
+  }
+
+  const [hh, mm] = input.split(':').map(Number);
+  const now = new Date();
+  const target = new Date();
+  target.setHours(hh, mm, 0, 0);
+  if (target <= now) target.setDate(target.getDate() + 1);
+
+  const waitSecs = Math.round((target - now) / 1000);
+  console.log(`\n  ${C.cyan}Scheduled for ${input}${C.reset} — ${fmtDuration(waitSecs)} from now`);
+  console.log(`  ${C.dim}Press Ctrl+C to cancel${C.reset}\n`);
+
+  await countdown(waitSecs, `Launching at ${input}`);
+
+  const confirmed = await confirmLaunch(selected.length);
+  if (!confirmed) {
+    console.log(`\n${C.dim}Aborted.${C.reset}`);
+    exit(0);
+  }
+  launchClaude(buildPrompt(selected), 'autonomous mode');
+}
+
+// ─── main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Guard: warn if not in a project directory
+  const looksLikeProject = fs.existsSync('.git') || fs.existsSync('package.json') || fs.existsSync('.claude');
+  if (!looksLikeProject) {
+    console.log('');
+    console.log(`${C.yellow}⚠  No project detected in ${process.cwd()}${C.reset}`);
+    console.log(`${C.dim}claskit should be run from your project root, not ~/ or /${C.reset}`);
+    const ans = await ask(`  Continue anyway? ${C.dim}[y/N]${C.reset}: `);
+    if (ans.toLowerCase() !== 'y') { exit(0); }
+    console.log('');
+  }
+
+  if (args.includes('--init')) {
+    runInit();
+    return;
+  }
+
+  // Onboarding — interactive setup if not initialized
+  if (!fs.existsSync(TODO_DIR)) {
+    console.log('');
+    console.log(`${C.yellow}claskit not set up in this project.${C.reset}`);
+    const doInit = await ask(`  Initialize now? ${C.dim}[Y/n]${C.reset}: `);
+    if (doInit.toLowerCase() === 'n') {
+      console.log(`\n${C.dim}Run: claskit --init${C.reset}`);
+      exit(0);
+    }
+    runInit();
+    console.log('');
+    const doTest = await ask(`  Add sample tasks to try claskit? ${C.dim}[Y/n]${C.reset}: `);
+    if (doTest.toLowerCase() !== 'n') {
+      const f1 = path.join(TODO_DIR, 'claskit-test-task-1.md');
+      const f2 = path.join(TODO_DIR, 'claskit-test-task-2.md');
+      fs.writeFileSync(f1, TEST_TASK_1);
+      fs.writeFileSync(f2, TEST_TASK_2);
+      console.log(`  ${C.green}✓${C.reset} Created 2 sample tasks in ${TODO_DIR}/`);
+    }
+    console.log('');
+    console.log(`${'─'.repeat(42)}`);
+    console.log(`  ${C.bold}Ready.${C.reset} Run: ${C.cyan}claskit --now${C.reset}`);
+    console.log(`${'─'.repeat(42)}`);
+    exit(0);
+  }
+
+  // Scan tasks
+  const tasks = fs.readdirSync(TODO_DIR)
+    .filter(f => f.endsWith('.md'))
+    .sort()
+    .map(f => path.join(TODO_DIR, f));
+
+  const taskCount = tasks.length;
+
+  // Header
+  console.log('');
+  console.log(C.cyan + box(
+    `${name}  v${version}`,
+    `Project: ${PROJECT_NAME}`,
+    `Tasks: ${taskCount} found`
+  ) + C.reset);
+  console.log('');
+
+  if (args.includes('--test')) {
+    const f1 = path.join(TODO_DIR, 'claskit-test-task-1.md');
+    const f2 = path.join(TODO_DIR, 'claskit-test-task-2.md');
+    fs.writeFileSync(f1, TEST_TASK_1);
+    fs.writeFileSync(f2, TEST_TASK_2);
+    console.log(`${C.green}Test tasks created:${C.reset}`);
+    console.log(`  ${C.dim}${f1}${C.reset}`);
+    console.log(`  ${C.dim}${f2}${C.reset}`);
+    console.log('');
+    console.log(`${C.bold}Now run:${C.reset}  ${C.cyan}claskit --now${C.reset}  (or ${C.cyan}pnpm claskit --now${C.reset})`);
+    console.log(`${C.dim}Select both test tasks → confirm → watch Claude create the output files.${C.reset}`);
+    console.log('');
+    console.log(`${C.dim}When done, run: claskit --clean-test${C.reset}`);
+    return;
+  }
+
+  if (args.includes('--clean-test')) {
+    const toDelete = [
+      path.join(TODO_DIR, 'claskit-test-task-1.md'),
+      path.join(TODO_DIR, 'claskit-test-task-2.md'),
+      path.join(DONE_DIR, 'claskit-test-task-1.md'),
+      path.join(DONE_DIR, 'claskit-test-task-2.md'),
+      '.claude/tasks/claskit-test-1.txt',
+      '.claude/tasks/claskit-test-2.txt',
+    ];
+    let removed = 0;
+    toDelete.forEach(f => {
+      if (fs.existsSync(f)) { fs.unlinkSync(f); removed++; }
+    });
+    console.log(`${C.green}Cleaned up ${removed} test file(s).${C.reset}`);
+    return;
+  }
+
+  if (taskCount === 0) {
+    console.log(`${C.yellow}No tasks found in ${TODO_DIR}${C.reset}`);
+    exit(0);
+  }
+
+  // List tasks
+  console.log(`${C.bold}Queued tasks:${C.reset}`);
+  tasks.forEach((f, i) => {
+    const title = taskTitle(f);
+    console.log(`  ${C.dim}${i + 1}.${C.reset} ${title}`);
+    console.log(`     ${C.dim}${path.basename(f)}${C.reset}`);
+  });
+  console.log('');
+
+  if (args.includes('--now')) {
+    await launchReal(tasks);
+    return;
+  }
+
+  // Interactive menu
+  console.log(`${C.bold}When to run?${C.reset}`);
+  const choice = await menu(['Now', 'Schedule (HH:MM)', 'Exit']);
+
+  switch (choice) {
+    case '1':
+      await launchReal(tasks);
+      break;
+
+    case '2':
+      await scheduleRun(tasks);
+      break;
+
+    case '3':
+    default:
+      console.log(`\n${C.dim}Bye.${C.reset}`);
+      exit(0);
+  }
+}
+
+if (require.main === module) {
+  main().catch(err => {
+    console.error(`${C.red}${err.message}${C.reset}`);
+    exit(1);
+  });
+}
+
+module.exports = { pad, box, fmtDuration, taskTitle, buildPrompt };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "claskit",
+  "version": "1.0.0",
+  "description": "Autonomous Claude Code task runner for spec-driven development",
+  "author": {
+    "name": "phucbm",
+    "url": "https://github.com/phucbm"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/phucbm/claskit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phucbm/claskit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/phucbm/claskit/issues"
+  },
+  "bin": {
+    "claskit": "bin/claskit.js"
+  },
+  "main": "./bin/claskit.js",
+  "files": [
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "task-runner",
+    "automation",
+    "cli",
+    "spec-driven",
+    "autonomous"
+  ]
+}