clawpilot 0.1.1 → 0.1.2

package/README.md

@@ -21,6 +21,25 @@ The installer also:
 npx clawpilot@latest
 ```
 
+## Quick Start
+
+```bash
+# Install into default ~/.openclaw
+npx -y clawpilot@latest install
+
+# Or install with custom schedule
+npx -y clawpilot@latest install --morning 08:30 --midday 13:30 --evening 21:00
+
+# Validate CLI
+npx -y clawpilot@latest --help
+```
+
+For isolated local verification:
+
+```bash
+node bin/cli.js install --home ./tmp-openclaw --yes --timezone UTC --force
+```
+
 Or run locally:
 
 ```bash
@@ -65,3 +84,17 @@ npm test
 ## Publish
 
 See `docs/PUBLISH_CHECKLIST.md`.
+
+## Troubleshooting
+
+### npm publish E403 (2FA required)
+
+If publish fails with:
+
+`403 Forbidden ... Two-factor authentication or granular access token with bypass 2fa enabled is required`
+
+Use one of these fixes:
+
+1. Enable npm 2FA for publishing and publish with OTP:
+   - `npm publish --access public --otp=<6-digit-code>`
+2. Use a granular access token with publish permission and bypass 2FA enabled.

package/bin/cli.js

@@ -2,8 +2,11 @@
 
 const os = require('node:os');
 const path = require('node:path');
+const readline = require('node:readline');
 const { installSkill, DEFAULT_SCHEDULE } = require('../src/install');
 
+const SCHEDULE_PATTERN = /^([01]\d|2[0-3]):([0-5]\d)$/;
+
 function printHelp() {
   console.log('clawpilot - OpenClaw productivity copilot');
   console.log('');
@@ -17,15 +20,28 @@ function printHelp() {
   console.log('Options:');
   console.log('  --home <path>       Override OpenClaw home directory');
   console.log('  --force             Replace existing clawpilot skill installation');
+  console.log('  --yes               Non-interactive mode (fail if required input is missing)');
+  console.log('  --timezone <IANA>   Timezone override (e.g. Asia/Taipei, UTC)');
   console.log(`  --morning <HH:mm>   Morning check-in time (default: ${DEFAULT_SCHEDULE.morning})`);
   console.log(`  --midday <HH:mm>    Midday check-in time (default: ${DEFAULT_SCHEDULE.midday})`);
   console.log(`  --evening <HH:mm>   Evening check-in time (default: ${DEFAULT_SCHEDULE.evening})`);
 }
 
+function readValueArg(args, index, flagName, missingValueFlags) {
+  const value = args[index + 1];
+  if (value === undefined || value.startsWith('--')) {
+    missingValueFlags.push(flagName);
+    return { value: undefined, nextIndex: index };
+  }
+  return { value, nextIndex: index + 1 };
+}
+
 function parseOptions(args) {
   const options = {
     force: false,
-    schedule: {}
+    yes: false,
+    schedule: {},
+    missingValueFlags: []
   };
 
   for (let index = 0; index < args.length; index += 1) {
@@ -34,24 +50,38 @@ function parseOptions(args) {
       options.force = true;
       continue;
     }
+    if (arg === '--yes') {
+      options.yes = true;
+      continue;
+    }
     if (arg === '--home') {
-      options.openClawHome = args[index + 1];
-      index += 1;
+      const { value, nextIndex } = readValueArg(args, index, '--home', options.missingValueFlags);
+      options.openClawHome = value;
+      index = nextIndex;
+      continue;
+    }
+    if (arg === '--timezone') {
+      const { value, nextIndex } = readValueArg(args, index, '--timezone', options.missingValueFlags);
+      options.timezone = value;
+      index = nextIndex;
       continue;
     }
     if (arg === '--morning') {
-      options.schedule.morning = args[index + 1];
-      index += 1;
+      const { value, nextIndex } = readValueArg(args, index, '--morning', options.missingValueFlags);
+      options.schedule.morning = value;
+      index = nextIndex;
       continue;
     }
     if (arg === '--midday') {
-      options.schedule.midday = args[index + 1];
-      index += 1;
+      const { value, nextIndex } = readValueArg(args, index, '--midday', options.missingValueFlags);
+      options.schedule.midday = value;
+      index = nextIndex;
       continue;
     }
     if (arg === '--evening') {
-      options.schedule.evening = args[index + 1];
-      index += 1;
+      const { value, nextIndex } = readValueArg(args, index, '--evening', options.missingValueFlags);
+      options.schedule.evening = value;
+      index = nextIndex;
       continue;
     }
     throw new Error(`Unknown option: ${arg}`);
@@ -60,6 +90,74 @@ function parseOptions(args) {
   return options;
 }
 
+function prompt(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function isValidTimezone(timezone) {
+  try {
+    Intl.DateTimeFormat('en-US', { timeZone: timezone }).format();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function validateSchedule(schedule) {
+  for (const [key, value] of Object.entries(schedule)) {
+    if (!SCHEDULE_PATTERN.test(value)) {
+      throw new Error(`Invalid ${key} time "${value}". Use HH:mm (24-hour format).`);
+    }
+  }
+}
+
+async function resolveMissingValues(options) {
+  const missing = [...new Set(options.missingValueFlags)];
+  if (missing.length === 0) {
+    return;
+  }
+
+  if (options.yes) {
+    throw new Error(`${missing[0]} requires a value when --yes is set.`);
+  }
+
+  if (!process.stdin.isTTY) {
+    throw new Error(`${missing[0]} requires a value. Re-run with ${missing[0]} <value> or use interactive terminal.`);
+  }
+
+  for (const flag of missing) {
+    if (flag === '--home') {
+      options.openClawHome = await prompt('OpenClaw home path: ');
+      continue;
+    }
+    if (flag === '--timezone') {
+      options.timezone = await prompt('Timezone (e.g. UTC, Asia/Taipei): ');
+      continue;
+    }
+    if (flag === '--morning') {
+      options.schedule.morning = await prompt('Morning check-in time (HH:mm): ');
+      continue;
+    }
+    if (flag === '--midday') {
+      options.schedule.midday = await prompt('Midday check-in time (HH:mm): ');
+      continue;
+    }
+    if (flag === '--evening') {
+      options.schedule.evening = await prompt('Evening check-in time (HH:mm): ');
+    }
+  }
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const command = args[0] || 'install';
@@ -79,19 +177,35 @@ async function main() {
 
   const projectRoot = path.resolve(__dirname, '..');
   const options = parseOptions(commandArgs);
+  await resolveMissingValues(options);
+  validateSchedule(options.schedule);
+
+  let timezone = options.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+  if (!timezone) {
+    if (options.yes) {
+      throw new Error('Timezone could not be detected. Provide --timezone <IANA name>.');
+    }
+    timezone = await prompt('Timezone (e.g. UTC, Asia/Taipei): ');
+  }
+  if (!isValidTimezone(timezone)) {
+    throw new Error(`Invalid timezone "${timezone}". Use a valid IANA timezone like UTC or Asia/Taipei.`);
+  }
+
   const openClawHome = options.openClawHome || process.env.OPENCLAW_HOME || path.join(os.homedir(), '.openclaw');
 
   const result = await installSkill({
     openClawHome,
     packageRoot: projectRoot,
     schedule: options.schedule,
-    force: options.force
+    force: options.force,
+    timezone
   });
 
   console.log(`Installed skill at: ${result.skillDir}`);
   console.log(`Updated config at: ${result.configPath}`);
   console.log(`Updated workspace SOUL at: ${result.workspaceSoulPath}`);
   console.log(`Updated workspace identity at: ${result.identityPath}`);
+  console.log('Next: run openclaw and start your morning Top-3 planning check-in.');
 }
 
 main().catch((error) => {

package/docs/PUBLISH_CHECKLIST.md

@@ -17,6 +17,7 @@ Use this checklist before publishing a new `clawpilot` version to npm.
    - `npm pack --dry-run`
 6. Publish:
    - `npm publish --access public`
+   - If your account has publish 2FA enabled: `npm publish --access public --otp=<6-digit-code>`
 7. Validate release:
    - `npm view clawpilot version`
    - `npx clawpilot@latest --help`

package/docs/plans/2026-02-12-0.1.2-plan.md

@@ -0,0 +1,52 @@
+# clawpilot 0.1.2 Plan
+
+## Goal
+
+Ship a practical upgrade that improves real daily usage after installation, while keeping the package lightweight and easy to run with `npx`.
+
+## Scope
+
+1. Better install UX
+   - Add `--yes` non-interactive mode for CI and scripted setup.
+   - Add `--timezone` option to override auto-detected timezone.
+   - Print a concise post-install summary with next commands.
+
+2. Productivity loop quality
+   - Expand `templates/soul-injection.md` with clearer response format:
+     - Morning: 3 measurable tasks.
+     - Midday: status and one unblock action.
+     - Evening: wins, lessons, and first task for tomorrow.
+   - Add a guardrail for rescue sprint frequency (max 2 per week in wording).
+
+3. Config reliability
+   - Preserve existing `skills.entries.clawpilot-productivity` fields when merging.
+   - Add tests for config merge with pre-existing custom fields.
+   - Add tests for repeated installs with mixed options.
+
+4. Documentation
+   - Add a troubleshooting section for npm publish errors (2FA and token setup).
+   - Add examples for local testing with `--home`.
+
+## Out of Scope (0.1.2)
+
+- Telegram or Discord runtime integration.
+- Network calls or external APIs.
+- Background schedulers.
+
+## Test Plan
+
+- Unit tests:
+  - Installer config merge behavior with existing settings.
+  - Schedule and timezone options parsing.
+  - Idempotent SOUL injection on repeated installs.
+- Smoke tests:
+  - `node bin/cli.js install --home <temp>`
+  - `node bin/cli.js install --home <temp> --force --yes`
+
+## Release Checklist
+
+1. `npm test`
+2. `npm pack --dry-run`
+3. `npm version patch`
+4. `npm publish --access public --otp=<code>`
+5. `git push origin main --tags`

package/docs/plans/2026-02-13-0.1.2-design.md

@@ -0,0 +1,115 @@
+# clawpilot 0.1.2 Design
+
+## Objective
+
+Deliver a reliable and practical 0.1.2 release for `clawpilot` that improves install UX and config safety while preserving the lightweight `npx` workflow.
+
+## Decisions Confirmed
+
+- Execution mode: continuous delivery for full 0.1.2 scope.
+- Installer interaction model: mixed mode.
+- `--yes` behavior: hard fail if required data is missing.
+- Priority order:
+  1. Config reliability
+  2. Install UX
+  3. Productivity template quality
+  4. Documentation
+
+## Architecture
+
+### 1. CLI Layer (`bin/cli.js`)
+
+- Parse command arguments and normalize options.
+- Support new flags:
+  - `--yes`
+  - `--timezone`
+  - existing schedule options (`--morning`, `--midday`, `--evening`)
+- Enforce validation rules:
+  - Invalid schedule/timezone format -> fail with clear error.
+  - Missing required values under `--yes` -> fail with exit code 1.
+- Produce concise post-install summary and next-step commands.
+
+### 2. Install Orchestration (`src/install.js`)
+
+- Keep orchestration responsibilities only:
+  - copy skill files
+  - apply config updates
+  - inject workspace files
+  - return structured install result
+- Delegate merge and workspace mutation to dedicated modules.
+
+### 3. Config Module (`src/config.js`)
+
+- Deep-merge behavior must preserve user custom fields.
+- Managed fields:
+  - `skills.entries.clawpilot-productivity.enabled`
+  - `skills.entries.clawpilot-productivity.mode`
+  - `skills.entries.clawpilot-productivity.schedule`
+  - `skills.entries.clawpilot-productivity.timezone`
+- Ensure `skills.load.extraDirs` is deduplicated.
+
+### 4. Workspace Module (`src/workspace.js`)
+
+- Marker-based injection for `workspace/SOUL.md`:
+  - replace clawpilot section if present
+  - keep non-clawpilot content untouched
+- Write `workspace/IDENTITY.md` deterministically from template.
+- Keep repeated installs idempotent.
+
+## Data Flow
+
+1. User runs `clawpilot install ...options`.
+2. CLI parses and validates options.
+3. Installer resolves defaults (schedule/timezone) or collects missing values in mixed mode.
+4. With `--yes`, unresolved required values immediately fail.
+5. Installer writes skill files and updates config/workspace.
+6. CLI prints summary including skill path, config path, and next command examples.
+
+## Error Handling
+
+- Invalid option values return explicit actionable messages.
+- `--yes` mode never prompts; it exits when data is incomplete.
+- Existing installation without `--force` fails safely.
+- Config parse failure falls back to empty config object, then rewrites valid JSON.
+
+## Testing Strategy
+
+### Unit Tests
+
+- Config merge preserves pre-existing unknown fields.
+- `skills.load.extraDirs` remains unique after repeated installs.
+- Timezone and schedule options are parsed and persisted correctly.
+- Marker injection stays single-instance after repeated install/force runs.
+
+### CLI/Behavior Tests
+
+- `--yes` with unresolved required input exits non-zero.
+- Happy path install succeeds with explicit options.
+- Reinstall with mixed options keeps idempotent state.
+
+### Smoke Tests
+
+- `node bin/cli.js install --home <temp>`
+- `node bin/cli.js install --home <temp> --force --yes`
+- `npm pack --dry-run`
+
+## Scope Boundaries
+
+In scope:
+- install UX upgrades
+- config reliability hardening
+- productivity prompt template improvements
+- troubleshooting docs
+
+Out of scope:
+- Telegram/Discord runtime integration
+- external API calls
+- background schedulers
+
+## Release Readiness
+
+0.1.2 is release-ready when:
+- `npm test` passes
+- smoke tests pass
+- README and troubleshooting are updated
+- package dry-run output is correct

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawpilot",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "OpenClaw productivity copilot installer and skill package.",
   "private": false,
   "bin": {

package/templates/soul-injection.md

@@ -1,14 +1,28 @@
 ## Clawpilot Productivity Loop
 
-Run this daily structure with minimal friction:
+Run this exact daily structure with minimal friction:
 
-- Morning: ask for 3 outcome-based tasks and make each one measurable.
-- Midday: collect status (`done`, `blocked`, or `deferred`) and unblock one thing.
-- Evening: summarize wins, note one lesson, and queue tomorrow's first action.
+### Morning (Plan)
+
+- Ask for exactly 3 outcome-based tasks.
+- Rewrite each task as measurable output (clear done criteria).
+- Ask for the first task to start now.
+
+### Midday (Status)
+
+- Ask for status per task: `done`, `blocked`, or `deferred`.
+- If blocked, suggest one concrete unblock action.
+- If behind, propose one 25-minute rescue sprint.
+
+### Evening (Review)
+
+- Summarize completed tasks and unfinished items.
+- Capture one lesson from the day.
+- Queue tomorrow's first action in one sentence.
 
 Coaching rules:
 
 - Keep guidance direct and practical.
 - Use supportive language, never guilt-driven language.
-- If progress is behind, offer one focused 25-minute rescue sprint.
+- Limit rescue sprints to at most two per week.
 - Avoid long motivational monologues.