codewake 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Obz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# codewake
+
+**Schedule your coding agents to pick up where they left off.**
+
+`codewake` is an interactive CLI that detects the coding agents installed on your machine — Claude Code, OpenAI Codex CLI, GitHub Copilot CLI, Gemini CLI, Cursor CLI, OpenCode, Aider, Goose, Amp, Qwen Code — lets you pick a session (or start a new one), choose a prompt, and launches the agent at the time you choose. Hit a usage limit at 2 AM? Schedule the resume for when it resets and go to sleep.
+
+- **Interactive console** — arrow keys, sensible defaults, a summary before anything is scheduled.
+- **Agent auto-detection** — scans your `PATH` for every supported agent; extend or override the list with a small JSON config.
+- **Session discovery** — lists your existing Claude Code and Codex sessions (with titles and timestamps) for the current project; other agents accept a session id or start fresh.
+- **Job management** — list, inspect logs, cancel, and clean up scheduled jobs from the console or with subcommands.
+- **Suspend-safe scheduling** — timers track the wall clock, so a laptop that sleeps through the launch time fires the job right after waking instead of drifting.
+- **Cross-platform** — Linux (systemd user timers), macOS, and Windows (detached waiter, `.cmd`-shim aware); CI runs on all three.
+- **Zero dependencies** — plain Node.js ≥ 18. Prompts are never passed through a shell, so no quoting surprises.
+
+## Install
+
+```bash
+npm install --global codewake
+```
+
+Or from a checkout of this repository:
+
+```bash
+npm link
+```
+
+## Quick start
+
+```bash
+codewake
+```
+
+The console walks you through it:
+
+1. **Pick an agent** — only agents actually found on your `PATH` are offered.
+2. **Pick a session** — existing sessions for the current project, enter a session id manually, or start a new session.
+3. **Prompt** — optional when resuming (defaults to `continue`), required for new sessions.
+4. **Permissions** — choose whether the agent runs unattended (its "skip permissions" / "yolo" flag) or interactively.
+5. **When** — right now, after a delay (`2h 30m`), or at a clock time (`06:00`).
+6. Review the exact command in the summary and confirm.
+
+```
+✔ Which agent do you want to launch? Claude Code
+✔ Which session do you want to resume? Ship the new API
+✔ Prompt to send (continue)
+✔ Skip permission prompts? [y/N] y
+✔ When should it launch? After a delay
+✔ Delay 2h 30m
+
+Summary
+  Agent        Claude Code
+  Session      550e8400-e29b-41d4-a716-446655440000
+  Prompt       continue
+  Permissions  skipped (unattended)
+  Launch       in 2h 30m (Jul 16, 04:10 PM)
+  Project      ~/work/my-app
+  Command      claude --resume 550e8400-… -p continue --dangerously-skip-permissions
+
+✔ Job k2f9qz-ab12 scheduled in 2h 30m.
+```
+
+## Managing jobs
+
+From the console (`codewake`) or directly:
+
+```bash
+codewake jobs             # list scheduled and finished jobs
+codewake logs <job-id>    # output captured from the agent run
+codewake cancel <job-id>  # cancel a pending job
+codewake clear            # drop finished/cancelled jobs from the list
+codewake agents           # which agents were detected, and where
+```
+
+## Non-interactive scheduling
+
+Everything the console does is available as flags — handy for scripts:
+
+```bash
+codewake schedule --agent claude --session 550e8400 --in 2h30m
+codewake schedule --agent codex --new --prompt "run the test suite and fix failures" --at 06:00 --skip-permissions
+codewake schedule --agent claude --session refactor-api --now --dry-run
+```
+
+`--dry-run` prints the exact command without scheduling anything.
+
+## Supported agents
+
+| Agent | Binary | Resume | New session | Session discovery |
+| --- | --- | --- | --- | --- |
+| Claude Code | `claude` | ✔ | ✔ | `~/.claude/projects` (per project, with titles) |
+| OpenAI Codex CLI | `codex` | ✔ | ✔ | `~/.codex/sessions` rollouts (filtered by cwd) |
+| GitHub Copilot CLI | `copilot` | ✔ | ✔ | `~/.copilot/history-session-state` |
+| Cursor CLI | `cursor-agent` | ✔ | ✔ | manual session id |
+| OpenCode | `opencode` | ✔ | ✔ | manual session id |
+| Aider | `aider` | ✔ (chat history) | ✔ | `.aider.chat.history.md` in the project |
+| Goose | `goose` | ✔ | ✔ | `~/.local/share/goose/sessions` |
+| Amp | `amp` | ✔ | ✔ | manual session id |
+| Gemini CLI | `gemini` | – | ✔ | – |
+| Qwen Code | `qwen` | – | ✔ | – |
+
+Agent CLIs move fast. If a flag changes upstream, or you use an agent we don't know about, you don't have to wait for a release — see the next section.
+
+## Custom agents
+
+Add or override agents in `~/.config/codewake/config.json` (or point `CODEWAKE_CONFIG` somewhere else). Entries have the same shape as the built-in registry (`lib/registry.js`):
+
+```json
+{
+  "agents": [
+    {
+      "id": "mycli",
+      "name": "My CLI",
+      "bins": ["mycli"],
+      "resume": { "args": ["--continue", "{session}", "--ask", "{prompt}"], "skip": ["--yes"] },
+      "create": { "args": ["--ask", "{prompt}"], "skip": ["--yes"] }
+    },
+    { "id": "claude", "bins": ["claude-nightly"] }
+  ],
+  "disabled": ["amp"]
+}
+```
+
+`{session}` and `{prompt}` are substituted as whole argv elements — commands are spawned directly, never through a shell. `CODEWAKE_BIN_<ID>` (e.g. `CODEWAKE_BIN_CLAUDE=/opt/claude`) overrides detection for a single agent.
+
+## How scheduling works
+
+- On **Linux with systemd**, jobs are armed with a transient user timer (`systemd-run --user --on-calendar=…`). Wall-clock timers keep ticking through laptop suspend and fire on resume if their time passed while the lid was closed. They survive the terminal closing; if your machine logs you out completely, enable lingering once: `loginctl enable-linger "$USER"`.
+- On **macOS, Windows, and Linux without systemd**, a small detached Node process waits for the launch time. It re-checks the wall clock every minute rather than sleeping once, so a machine that suspends overnight launches the job right after waking instead of drifting by the suspended time. It survives the terminal closing, but not a reboot.
+
+A session can only have **one pending job** at a time — scheduling a second resume for the same session is refused until you cancel the first, so two agents never race each other over one transcript. Jobs whose launch time passed without running (e.g. after a reboot) show up as `overdue` in `codewake jobs`, with how late they are — reschedule them.
+
+### Where state and logs live
+
+| OS | Job state | Execution logs |
+| --- | --- | --- |
+| Linux | `~/.local/state/codewake/` | `~/.local/state/codewake/logs/` |
+| macOS | `~/Library/Application Support/codewake/` | `~/Library/Logs/codewake/` |
+| Windows | `%LOCALAPPDATA%\codewake\` | `%LOCALAPPDATA%\codewake\Logs\` |
+
+Every job run captures the agent's stdout/stderr to `<job-id>.log`, readable with `codewake logs <job-id>`. `CODEWAKE_STATE_DIR` overrides the state location (logs move under `<dir>/logs`). On Windows, npm-installed agents (`.cmd` shims) are launched through `cmd.exe` with every argument escaped — never an interpolated shell string.
+
+## A word about unattended runs
+
+Choosing *skip permissions* passes the agent's own bypass flag (for example `--dangerously-skip-permissions` for Claude Code). The agent will edit files and run commands without asking. Only schedule projects you trust, review the prompt before confirming, and keep your work under version control. `codewake` always shows the exact command in the summary and defaults to **not** skipping permissions.
+
+## Development
+
+```bash
+npm test                        # zero-dependency test suite (node --test)
+node bin/codewake.js        # run the console from the checkout
+```
+
+The test suite covers argument parsing, duration/time parsing, the agent registry, command building, session discovery (with fixtures), the job store and both scheduling backends, and the interactive console end to end (driven through fake terminals).
+
+## License
+
+MIT
+
+This is a new line for testing purposes.

package/bin/codewake.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../lib/cli.js';
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(`codewake: ${error.message}`);
+  process.exitCode = 1;
+});

package/lib/agents.js

@@ -0,0 +1,119 @@
+import { accessSync, constants, existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, isAbsolute, join, resolve } from 'node:path';
+import { BUILTIN_AGENTS } from './registry.js';
+
+export function configPath(env = process.env) {
+  if (env.CODEWAKE_CONFIG) return resolve(env.CODEWAKE_CONFIG);
+  const configHome = env.XDG_CONFIG_HOME || resolve(homedir(), '.config');
+  return resolve(configHome, 'codewake', 'config.json');
+}
+
+/**
+ * Built-in registry merged with the user's config file. The config may
+ * override built-ins by id, add brand new agents, and disable ids:
+ *   { "agents": [{ "id": "mycli", ... }], "disabled": ["amp"] }
+ */
+export function loadAgents({ env = process.env } = {}) {
+  const agents = new Map(BUILTIN_AGENTS.map((agent) => [agent.id, agent]));
+  const path = configPath(env);
+  if (!existsSync(path)) return [...agents.values()];
+  let config;
+  try {
+    config = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw new Error(`Could not parse ${path}: ${error.message}`);
+  }
+  for (const entry of config.agents ?? []) {
+    if (!entry || typeof entry.id !== 'string' || !entry.id) {
+      throw new Error(`Every agent in ${path} needs a string "id".`);
+    }
+    const merged = { ...agents.get(entry.id), ...entry };
+    validateAgent(merged, path);
+    agents.set(merged.id, merged);
+  }
+  for (const id of config.disabled ?? []) agents.delete(id);
+  return [...agents.values()];
+}
+
+function validateAgent(agent, source) {
+  const problem = (message) => new Error(`Invalid agent "${agent.id}" in ${source}: ${message}`);
+  if (!agent.name || typeof agent.name !== 'string') throw problem('missing "name".');
+  if (!Array.isArray(agent.bins) || !agent.bins.length) throw problem('"bins" must be a non-empty array.');
+  if (!agent.resume && !agent.create) throw problem('needs a "resume" or "create" command spec.');
+  for (const key of ['resume', 'create']) {
+    const spec = agent[key];
+    if (spec && (!Array.isArray(spec.args) || !spec.args.length)) {
+      throw problem(`"${key}.args" must be a non-empty array.`);
+    }
+  }
+}
+
+/** Resolve a command on PATH without spawning a shell. */
+export function which(command, env = process.env) {
+  const tryPath = (candidate) => {
+    try {
+      accessSync(candidate, constants.X_OK);
+      return statSync(candidate).isFile() ? candidate : null;
+    } catch {
+      return null;
+    }
+  };
+  if (command.includes('/') || command.includes('\\')) {
+    return tryPath(isAbsolute(command) ? command : resolve(command));
+  }
+  const extensions = process.platform === 'win32'
+    ? (env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';').map((ext) => ext.toLowerCase())
+    : [''];
+  for (const dir of (env.PATH || '').split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of extensions) {
+      const found = tryPath(join(dir, command + ext));
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+/**
+ * Probe which agents are installed. Returns [{ agent, bin }] for every
+ * registered agent; `bin` is the resolved executable path or null.
+ * CODEWAKE_BIN_<ID> overrides detection for a single agent.
+ */
+export function detectAgents(agents, { env = process.env } = {}) {
+  return agents.map((agent) => {
+    const override = env[`CODEWAKE_BIN_${agent.id.toUpperCase().replaceAll('-', '_')}`];
+    const bin = override
+      ? which(override, env)
+      : agent.bins.map((candidate) => which(candidate, env)).find(Boolean) ?? null;
+    return { agent, bin };
+  });
+}
+
+/**
+ * Build the argv for a job. Placeholders are substituted inside argv
+ * elements — the command is spawned directly, never through a shell.
+ */
+export function buildCommand(agent, { mode, sessionId, prompt, skipPermissions = false }) {
+  const spec = mode === 'resume' ? agent.resume : agent.create;
+  if (!spec) {
+    const action = mode === 'resume' ? 'resuming sessions' : 'starting new sessions';
+    throw new Error(`${agent.name} does not support ${action} from codewake.`);
+  }
+  // Single-pass substitution: substituted values are never re-scanned, so a
+  // session id containing the literal text "{prompt}" (or vice versa) cannot
+  // be re-expanded.
+  const values = { session: sessionId ?? '', prompt: prompt ?? '' };
+  const args = spec.args.map((part) =>
+    part.replace(/\{(session|prompt)\}/g, (_match, token) => values[token]),
+  );
+  if (skipPermissions && spec.skip) args.push(...spec.skip);
+  return args;
+}
+
+/** Shell-quoted preview of a command, for display only. */
+export function commandPreview(bin, args) {
+  return [bin, ...args]
+    .map((part) => (/[^\w@%+=:,./-]/.test(part) || part === '' ? `'${part.replaceAll("'", "'\\''")}'` : part))
+    .join(' ');
+}

package/lib/cli.js

@@ -0,0 +1,245 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildCommand, commandPreview, detectAgents, loadAgents } from './agents.js';
+import {
+  cancelJob,
+  clearJobs,
+  listJobs,
+  logFile,
+  runJob,
+  scheduleJob,
+  waitJob,
+} from './jobs.js';
+import { describeRunAt, parseClockTime, parseDuration } from './time.js';
+import { color } from './tui.js';
+import { runWizard, viewJobs } from './wizard.js';
+
+const DEFAULT_RESUME_PROMPT = 'continue';
+const PACKAGE_JSON = fileURLToPath(new URL('../package.json', import.meta.url));
+
+export function version() {
+  return JSON.parse(readFileSync(PACKAGE_JSON, 'utf8')).version;
+}
+
+export function usage() {
+  return `${color.bold('codewake')} — schedule your coding agents to pick up where they left off
+
+Usage:
+  codewake                     Interactive console (detect agents, pick a
+                               session, schedule the resume job)
+  codewake jobs                List scheduled and finished jobs
+  codewake logs <job-id>       Show the output of a job
+  codewake cancel <job-id>     Cancel a pending job
+  codewake clear               Remove finished jobs from the list
+  codewake agents              Show which agents are installed
+  codewake schedule [options]  Non-interactive scheduling
+
+Schedule options:
+  --agent <id>          Agent to launch (see "codewake agents")
+  --session <id>        Session to resume
+  --new                 Start a new session instead of resuming
+  --prompt <text>       Prompt to send (resume default: "${DEFAULT_RESUME_PROMPT}";
+                        required with --new)
+  --skip-permissions    Let the agent run unattended (its "yolo" flag)
+  --project <dir>       Working directory (default: current directory)
+  --in <duration>       Launch after a delay, e.g. "2h 30m"
+  --at <HH:MM>          Launch at a time (today, or tomorrow if past)
+  --now                 Launch immediately (default)
+  --bin <path>          Override the detected executable
+  --dry-run             Print what would run without scheduling
+
+Examples:
+  codewake
+  codewake schedule --agent claude --session 550e8400 --in 2h30m
+  codewake schedule --agent codex --new --prompt "run the test suite" --at 06:00`;
+}
+
+export function parseArgs(argv) {
+  const [first, ...rest] = argv;
+  if (first === undefined) return { command: 'wizard' };
+  switch (first) {
+    case 'help':
+    case '--help':
+    case '-h':
+      return { command: 'help' };
+    case '--version':
+    case '-v':
+      return { command: 'version' };
+    case 'jobs':
+    case 'list':
+      return { command: 'jobs' };
+    case 'agents':
+      return { command: 'agents' };
+    case 'clear':
+      return { command: 'clear' };
+    case 'logs':
+      if (!rest[0]) throw new Error('Usage: codewake logs <job-id>');
+      return { command: 'logs', jobId: rest[0] };
+    case 'cancel':
+      if (!rest[0]) throw new Error('Usage: codewake cancel <job-id>');
+      return { command: 'cancel', jobId: rest[0] };
+    case 'schedule':
+      return parseScheduleArgs(rest);
+    case '--run':
+      return { command: 'run', jobId: rest[0] };
+    case '--wait':
+      return { command: 'wait', jobId: rest[0] };
+    default:
+      throw new Error(`Unknown command: ${first}. Run "codewake --help".`);
+  }
+}
+
+function parseScheduleArgs(argv) {
+  const result = {
+    command: 'schedule',
+    agentId: null,
+    sessionId: null,
+    isNew: false,
+    prompt: null,
+    skipPermissions: false,
+    project: process.cwd(),
+    when: { type: 'now' },
+    bin: null,
+    dryRun: false,
+  };
+  const value = (i, flag) => {
+    if (argv[i + 1] === undefined) throw new Error(`${flag} needs a value.`);
+    return argv[i + 1];
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const flag = argv[i];
+    if (flag === '--agent') result.agentId = value(i, flag), i += 1;
+    else if (flag === '--session') result.sessionId = value(i, flag), i += 1;
+    else if (flag === '--new') result.isNew = true;
+    else if (flag === '--prompt') result.prompt = value(i, flag), i += 1;
+    else if (flag === '--skip-permissions') result.skipPermissions = true;
+    else if (flag === '--project') result.project = resolve(value(i, flag)), i += 1;
+    else if (flag === '--in') result.when = { type: 'in', value: value(i, flag) }, i += 1;
+    else if (flag === '--at') result.when = { type: 'at', value: value(i, flag) }, i += 1;
+    else if (flag === '--now') result.when = { type: 'now' };
+    else if (flag === '--bin') result.bin = value(i, flag), i += 1;
+    else if (flag === '--dry-run') result.dryRun = true;
+    else throw new Error(`Unknown option: ${flag}. Run "codewake --help".`);
+  }
+  if (!result.agentId) throw new Error('--agent is required. See "codewake agents" for ids.');
+  if (result.isNew && result.sessionId) throw new Error('Use either --session or --new, not both.');
+  if (!result.isNew && !result.sessionId) throw new Error('Pass --session <id> to resume, or --new to start fresh.');
+  if (result.isNew && !result.prompt?.trim()) throw new Error('--prompt is required when starting a new session.');
+  return result;
+}
+
+export function resolveRunAt(when, now = new Date()) {
+  if (when.type === 'in') return new Date(now.getTime() + parseDuration(when.value) * 1000);
+  if (when.type === 'at') return parseClockTime(when.value, now);
+  return now;
+}
+
+function scheduleFromArgs(args, env = process.env) {
+  const detected = detectAgents(loadAgents({ env }), { env });
+  const entry = detected.find((candidate) => candidate.agent.id === args.agentId);
+  if (!entry) {
+    const known = detected.map((candidate) => candidate.agent.id).join(', ');
+    throw new Error(`Unknown agent "${args.agentId}". Known agents: ${known}.`);
+  }
+  const bin = args.bin ?? entry.bin;
+  if (!bin) {
+    throw new Error(`${entry.agent.name} is not installed (looked for: ${entry.agent.bins.join(', ')}). Use --bin to point at it.`);
+  }
+  const mode = args.isNew ? 'create' : 'resume';
+  const prompt = args.prompt?.trim() || DEFAULT_RESUME_PROMPT;
+  const commandArgs = buildCommand(entry.agent, {
+    mode,
+    sessionId: args.sessionId,
+    prompt,
+    skipPermissions: args.skipPermissions,
+  });
+  const job = scheduleJob({
+    agent: entry.agent,
+    bin,
+    args: commandArgs,
+    mode,
+    sessionId: args.sessionId,
+    prompt,
+    skipPermissions: args.skipPermissions,
+    project: args.project,
+    runAt: resolveRunAt(args.when),
+  }, { dryRun: args.dryRun, env });
+  return { job, preview: commandPreview(bin, commandArgs) };
+}
+
+export function renderAgentsReport(detected) {
+  const nameWidth = Math.max(...detected.map(({ agent }) => `${agent.name} (${agent.id})`.length));
+  return detected
+    .map(({ agent, bin }) => {
+      const mark = bin ? color.green('✔') : color.dim('✘');
+      const location = bin ? color.dim(bin) : color.dim('not found');
+      const caps = [agent.resume ? 'resume' : null, agent.create ? 'new' : null].filter(Boolean).join(' + ');
+      const name = `${agent.name} (${agent.id})`.padEnd(nameWidth);
+      return `${mark} ${name}  ${caps.padEnd(12)} ${location}`;
+    })
+    .join('\n');
+}
+
+export async function main(argv) {
+  const args = parseArgs(argv);
+  switch (args.command) {
+    case 'help':
+      console.log(usage());
+      return;
+    case 'version':
+      console.log(version());
+      return;
+    case 'wizard':
+      if (!process.stdin.isTTY) {
+        throw new Error('The interactive console needs a terminal. Use "codewake schedule" with flags instead.');
+      }
+      await runWizard({ version: version() });
+      return;
+    case 'jobs':
+      viewJobs(process.stdout);
+      return;
+    case 'logs': {
+      const path = logFile(args.jobId);
+      if (!existsSync(path)) {
+        throw new Error(`No log for job ${args.jobId} yet (it appears at ${path} once the job runs).`);
+      }
+      process.stdout.write(readFileSync(path, 'utf8'));
+      return;
+    }
+    case 'cancel': {
+      const { warning } = cancelJob(args.jobId);
+      console.log(`${color.green('✔')} Cancelled ${args.jobId}.`);
+      if (warning) console.log(`${color.yellow('!')} ${warning}`);
+      return;
+    }
+    case 'clear': {
+      const removed = clearJobs();
+      console.log(removed.length ? `Removed ${removed.length} finished job(s).` : 'Nothing to clean up.');
+      return;
+    }
+    case 'agents':
+      console.log(renderAgentsReport(detectAgents(loadAgents())));
+      return;
+    case 'run':
+      await runJob(args.jobId);
+      return;
+    case 'wait':
+      await waitJob(args.jobId);
+      return;
+    case 'schedule': {
+      const { job, preview } = scheduleFromArgs(args);
+      if (args.dryRun) {
+        console.log(`Would launch ${describeRunAt(job.runAt)} in ${job.project}:`);
+        console.log(`  ${preview}`);
+        return;
+      }
+      console.log(`${color.green('✔')} Job ${color.bold(job.id)} scheduled ${describeRunAt(job.runAt)}.`);
+      console.log(color.dim(`  ${preview}`));
+      console.log(color.dim(`  Manage it with "codewake jobs" or "codewake cancel ${job.id}".`));
+      return;
+    }
+    default:
+      throw new Error(`Unhandled command: ${args.command}`);
+  }
+}