step-overflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qiichos
+
+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.ja.md

@@ -0,0 +1,111 @@
+# step-overflow
+
+[English](./README.md) | [日本語](./README.ja.md)
+
+ウォーキング記録CLIツール。歩いた記録をGitHubに保存し、GitHub Pagesで可視化します。
+
+## インストール
+
+```bash
+npm install -g step-overflow
+```
+
+### 必要なもの
+
+- Node.js >= 18
+- git
+- [GitHub CLI](https://cli.github.com/) (`gh`)
+
+## クイックスタート
+
+```bash
+# 初期設定（GitHubリポジトリ作成、速度・体重設定、ルート選択）
+stp init
+
+# 60分のウォーキングを記録
+stp add 60
+
+# ダッシュボードをブラウザで開く
+stp open
+```
+
+## コマンド
+
+| コマンド | 説明 |
+|---------|------|
+| `stp init` | 初期設定（リポジトリ、速度、体重、ルート） |
+| `stp add <分>` | ウォーキングを記録 |
+| `stp sync` | 未プッシュのコミットを送信 |
+| `stp open` | ダッシュボードをローカルで開く |
+| `stp open --remote` | GitHub Pagesで開く（公開リポジトリ） |
+| `stp status` | 現在の状態、ルート進捗、実績を表示 |
+| `stp config speed <値>` | デフォルト速度を変更（km/h） |
+| `stp config weight <値>` | 体重を変更（kg、`none`でクリア） |
+| `stp config route` | ルートを変更 |
+| `stp log` | 最近の記録をターミナルに表示 |
+
+### `stp add` オプション
+
+```bash
+stp add 60                        # デフォルト速度で60分
+stp add 60 --speed 5.0            # 5 km/hで60分
+stp add 60 --date 2026-03-01      # 日付を指定して記録
+```
+
+## ジャーニー
+
+初期設定時にルートを選び、歩いた距離に応じて仮想の旅を進めます:
+
+| タイトル | ルート | 距離 | 難易度 |
+|---------|-------|------|--------|
+| ⛷️ Tour du Mont Blanc | Chamonix → Chamonix | 170 km | ★☆☆☆☆ |
+| 🏯 Tokaido | Tokyo → Osaka | 495 km | ★☆☆☆☆ |
+| 🕊️ Camino de Santiago | Lisbon → Santiago | 620 km | ★★☆☆☆ |
+| 🏛️ Nile Valley | Aswan → Cairo | 1,100 km | ★★☆☆☆ |
+| 🐘 Hannibal's March | Cartagena → Rome | 1,500 km | ★★☆☆☆ |
+| ⛪ Via Francigena | Canterbury → Rome | 1,900 km | ★★★☆☆ |
+| 🏜️ Trans-Saharan | Timbuktu → Marrakech | 2,200 km | ★★★☆☆ |
+| 🏔️ Qhapaq Ñan | Quito → Cusco | 2,500 km | ★★★☆☆ |
+| ⛵ Spice Route | Banda Neira → Singapore | 3,500 km | ★★★☆☆ |
+| 🇺🇸 Route 66 | Chicago → Los Angeles | 3,940 km | ★★★☆☆ |
+| 🐫 Silk Road | Xi'an → Constantinople | 7,000 km | ★★★★☆ |
+| 🌍 Around the World | London → London | 40,075 km | ★★★★★ |
+
+各ルートには中継地点があり、到着するたびに通知されます。ルートを完走したら、次の冒険を選びましょう。
+
+## 実績
+
+49の実績を歩いてアンロック:
+
+- **距離**: First Step, Century, Thousand Miles, 10K Club, ...
+- **ルート**: Tokaido Master, Pilgrim, Silk Merchant, Globe Trotter, ...
+- **1回の記録**: 5K Walk, Half Marathon, Marathon, Speed Demon, ...
+- **時間・習慣**: Early Bird, Night Owl, Weekend Warrior, Double Up
+- **記録回数**: 5, 10, 50, 100回、以降100回刻みで1,000回まで
+
+## データ
+
+記録は `~/.local/share/step-overflow/<リポジトリ>/data/walking.csv` に保存:
+
+```
+datetime,time_min,speed_kmh,distance_km,weight_kg
+2026-03-06T07:30:00,60,4.0,4.00,70
+```
+
+設定は `~/.config/step-overflow/config.json` に保存。
+
+パスは [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/) に準拠。`$XDG_CONFIG_HOME` と `$XDG_DATA_HOME` で変更可能。
+
+## ダッシュボード
+
+Webダッシュボード（`stp open`）は3つのタブで構成:
+
+- **Walking**: サマリーカード、日次/累計チャート、記録テーブル
+- **Journey**: ルート進捗の可視化と中継地点
+- **Achievements**: 実績の一覧（アンロック済み/未アンロック）
+
+カロリーはMETs（代謝当量）に基づき、歩行速度から計算されます。
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,111 @@
+# step-overflow
+
+[English](./README.md) | [日本語](./README.ja.md)
+
+CLI walking log tool. Record walks, sync to GitHub, visualize on GitHub Pages.
+
+## Install
+
+```bash
+npm install -g step-overflow
+```
+
+### Requirements
+
+- Node.js >= 18
+- git
+- [GitHub CLI](https://cli.github.com/) (`gh`)
+
+## Quick Start
+
+```bash
+# Initial setup (creates GitHub repo, local config, choose a journey)
+stp init
+
+# Record a 60-minute walk
+stp add 60
+
+# View dashboard in browser
+stp open
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `stp init` | Interactive setup (repo, speed, weight, journey) |
+| `stp add <minutes>` | Record a walk |
+| `stp sync` | Push unpushed commits |
+| `stp open` | Open dashboard locally |
+| `stp open --remote` | Open GitHub Pages (public repos) |
+| `stp status` | Show current status, journey progress, achievements |
+| `stp config speed <value>` | Update default speed (km/h) |
+| `stp config weight <value>` | Update weight (kg, `none` to clear) |
+| `stp config route` | Change journey route |
+| `stp log` | Show recent records in terminal |
+
+### `stp add` options
+
+```bash
+stp add 60                        # 60 min at default speed
+stp add 60 --speed 5.0            # 60 min at 5 km/h
+stp add 60 --date 2026-03-01      # Backdate a record
+```
+
+## Journey
+
+Choose a route during setup and track your virtual progress as you walk:
+
+| Title | Route | Distance | Difficulty |
+|-------|-------|----------|------------|
+| ⛷️ Tour du Mont Blanc | Chamonix → Chamonix | 170 km | ★☆☆☆☆ |
+| 🏯 Tokaido | Tokyo → Osaka | 495 km | ★☆☆☆☆ |
+| 🕊️ Camino de Santiago | Lisbon → Santiago | 620 km | ★★☆☆☆ |
+| 🏛️ Nile Valley | Aswan → Cairo | 1,100 km | ★★☆☆☆ |
+| 🐘 Hannibal's March | Cartagena → Rome | 1,500 km | ★★☆☆☆ |
+| ⛪ Via Francigena | Canterbury → Rome | 1,900 km | ★★★☆☆ |
+| 🏜️ Trans-Saharan | Timbuktu → Marrakech | 2,200 km | ★★★☆☆ |
+| 🏔️ Qhapaq Ñan | Quito → Cusco | 2,500 km | ★★★☆☆ |
+| ⛵ Spice Route | Banda Neira → Singapore | 3,500 km | ★★★☆☆ |
+| 🇺🇸 Route 66 | Chicago → Los Angeles | 3,940 km | ★★★☆☆ |
+| 🐫 Silk Road | Xi'an → Constantinople | 7,000 km | ★★★★☆ |
+| 🌍 Around the World | London → London | 40,075 km | ★★★★★ |
+
+Each route has waypoints — you'll be notified when you arrive at each city along the way. Complete a route and choose your next adventure.
+
+## Achievements
+
+Unlock 49 achievements as you walk:
+
+- **Distance**: First Step, Century, Thousand Miles, 10K Club, ...
+- **Route**: Tokaido Master, Pilgrim, Silk Merchant, Globe Trotter, ...
+- **Single Walk**: 5K Walk, Half Marathon, Marathon, Speed Demon, ...
+- **Time & Habit**: Early Bird, Night Owl, Weekend Warrior, Double Up
+- **Walk Count**: Milestones at 5, 10, 50, 100, and every 100 up to 1,000
+
+## Data
+
+Records are stored in `~/.local/share/step-overflow/<repo>/data/walking.csv`:
+
+```
+datetime,time_min,speed_kmh,distance_km,weight_kg
+2026-03-06T07:30:00,60,4.0,4.00,70
+```
+
+Config is stored in `~/.config/step-overflow/config.json`.
+
+Paths follow the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/). Override with `$XDG_CONFIG_HOME` and `$XDG_DATA_HOME`.
+
+## Dashboard
+
+The web dashboard (`stp open`) has three tabs:
+
+- **Walking**: Summary cards, daily/cumulative charts, record table
+- **Journey**: Route progress visualization with waypoints
+- **Achievements**: Unlocked/locked achievement grid
+
+Calories are calculated using METs (Metabolic Equivalent of Task) based on walking speed.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { defineCommand, runMain } from "citty";
+import { readFileSync } from "node:fs";
+import { initCommand } from "./commands/init.js";
+import { addCommand } from "./commands/add.js";
+import { syncCommand } from "./commands/sync.js";
+import { openCommand } from "./commands/open.js";
+import { statusCommand } from "./commands/status.js";
+import { configCommand } from "./commands/config.js";
+import { logCommand } from "./commands/log.js";
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+const main = defineCommand({
+    meta: {
+        name: "stp",
+        version,
+        description: "CLI walking log tool",
+    },
+    subCommands: {
+        init: initCommand,
+        add: addCommand,
+        sync: syncCommand,
+        open: openCommand,
+        status: statusCommand,
+        config: configCommand,
+        log: logCommand,
+    },
+});
+runMain(main);

package/dist/commands/add.js

@@ -0,0 +1,188 @@
+import { defineCommand } from "citty";
+import { consola } from "consola";
+import { join } from "node:path";
+import { writeFile } from "node:fs/promises";
+import { loadConfig, saveConfig, getCsvPath } from "../lib/config.js";
+import { appendRecord, readRecords } from "../lib/csv.js";
+import { calcCalories } from "../lib/calories.js";
+import { generateIndexHtml } from "../lib/html.js";
+import { gitAdd, gitCommit, gitPush } from "../lib/git.js";
+import { playWalkAnimation } from "../lib/animation.js";
+import { getRoute, getProgress, getNewlyPassedWaypoints, progressBar, formatRouteOption, ROUTES, } from "../lib/routes.js";
+import { checkNewAchievements } from "../lib/achievements.js";
+import { promptSelect } from "../lib/prompt.js";
+export const addCommand = defineCommand({
+    meta: { name: "add", description: "Add a walking record" },
+    args: {
+        time_min: {
+            type: "positional",
+            description: "Walking time in minutes",
+            required: true,
+        },
+        speed: {
+            type: "string",
+            description: "Walking speed (km/h)",
+        },
+        date: {
+            type: "string",
+            description: "Record date (ISO format or YYYY-MM-DD)",
+        },
+    },
+    run: async ({ args }) => {
+        const config = await loadConfig();
+        const timeMin = parseFloat(args.time_min);
+        if (isNaN(timeMin) || timeMin <= 0) {
+            consola.error("Invalid time. Provide a positive number in minutes.");
+            process.exit(1);
+        }
+        const speedKmh = args.speed ? parseFloat(args.speed) : config.default_speed;
+        if (isNaN(speedKmh) || speedKmh <= 0) {
+            consola.error("Invalid speed.");
+            process.exit(1);
+        }
+        let datetime;
+        if (args.date) {
+            const d = new Date(args.date);
+            if (isNaN(d.getTime())) {
+                consola.error("Invalid date format. Use YYYY-MM-DD or ISO 8601.");
+                process.exit(1);
+            }
+            datetime = d.toISOString().slice(0, 19);
+        }
+        else {
+            datetime = new Date().toISOString().slice(0, 19);
+        }
+        const distanceKm = (timeMin / 60) * speedKmh;
+        const csvPath = getCsvPath(config);
+        await appendRecord(csvPath, {
+            datetime,
+            time_min: timeMin,
+            speed_kmh: speedKmh,
+            distance_km: distanceKm,
+            weight_kg: config.weight_kg,
+        });
+        // Record summary line
+        let recordLine = `${distanceKm.toFixed(2)} km  |  ${timeMin} min  |  ${speedKmh} km/h`;
+        if (config.weight_kg) {
+            const cal = calcCalories(speedKmh, timeMin, config.weight_kg);
+            recordLine += `  |  ${cal} kcal`;
+        }
+        consola.success(recordLine);
+        // --- Compute all state before HTML generation ---
+        const records = await readRecords(csvPath);
+        const totalKm = records.reduce((s, r) => s + r.distance_km, 0);
+        // Journey
+        const journey = config.journey;
+        const route = journey ? getRoute(journey.route_id) : undefined;
+        let justCompleted = false;
+        let newWaypoints = [];
+        let journeyProgress;
+        if (journey && route) {
+            const journeyKm = Math.max(0, totalKm - journey.started_km);
+            const prevJourneyKm = Math.max(0, journeyKm - distanceKm);
+            journeyProgress = getProgress(route, journeyKm);
+            newWaypoints = getNewlyPassedWaypoints(route, prevJourneyKm, journeyKm);
+            justCompleted = prevJourneyKm < route.total_km && journeyKm >= route.total_km;
+            if (justCompleted && !journey.completed_routes.includes(route.id)) {
+                journey.completed_routes.push(route.id);
+            }
+        }
+        // Achievements
+        const unlocked = config.achievements ?? {};
+        const completedRoutes = journey?.completed_routes ?? [];
+        const ctx = { allRecords: records, totalKm, completedRoutes };
+        const newAchievements = checkNewAchievements(ctx, unlocked);
+        for (const a of newAchievements) {
+            unlocked[a.id] = new Date().toISOString().slice(0, 19);
+        }
+        // Save config if anything changed
+        if (newAchievements.length > 0 || justCompleted) {
+            config.achievements = unlocked;
+            await saveConfig(config);
+        }
+        // --- Git sync (with updated config) runs in parallel with animation ---
+        const cwd = config.local_path;
+        const gitSync = (async () => {
+            await writeFile(join(cwd, "docs", "index.html"), generateIndexHtml(config));
+            await gitAdd(["data/walking.csv", "docs/index.html"], cwd);
+            try {
+                await gitCommit(`Walk: ${timeMin} min, ${distanceKm.toFixed(2)} km`, cwd);
+            }
+            catch {
+                return "commit-failed";
+            }
+            try {
+                await gitPush(cwd);
+                return "pushed";
+            }
+            catch {
+                return "push-failed";
+            }
+        })();
+        await playWalkAnimation(gitSync);
+        // --- Display notifications ---
+        // Waypoint arrivals
+        if (newWaypoints.length > 0 && journeyProgress) {
+            consola.log("");
+            for (const w of newWaypoints) {
+                consola.success(`You've arrived in ${w.name} \u2014 ${w.description}`);
+            }
+            if (journeyProgress.next) {
+                consola.info(`Next stop: ${journeyProgress.next.name} \u2014 ${Math.ceil(journeyProgress.nextDistance)} km to go`);
+            }
+        }
+        // Journey completion or progress
+        if (journey && route) {
+            if (justCompleted) {
+                const startDate = journey.started_at.split("T")[0];
+                const today = new Date().toISOString().slice(0, 10);
+                const days = Math.ceil((new Date(today).getTime() - new Date(startDate).getTime()) / (1000 * 60 * 60 * 24)) + 1;
+                consola.log("");
+                consola.box(`Journey Complete!\n\n` +
+                    `${route.from} \u2192 ${route.to} (${route.total_km.toLocaleString()} km)\n` +
+                    `Completed in ${days} days`);
+            }
+            else if (journeyProgress) {
+                consola.log("");
+                consola.log(`  \u{1F6B6} ${route.from} \u2192 ${route.to}  ` +
+                    `${journeyProgress.percent.toFixed(1)}%  (${Math.floor(journeyProgress.walkedKm)} / ${route.total_km.toLocaleString()} km)`);
+                consola.log(`  ${progressBar(journeyProgress.percent)}`);
+            }
+        }
+        // Achievements
+        if (newAchievements.length > 0) {
+            consola.log("");
+            for (const a of newAchievements) {
+                consola.success(`\u{1F3C5} ${a.name} \u2014 ${a.description}`);
+            }
+        }
+        // Next route prompt on completion
+        if (justCompleted) {
+            consola.log("");
+            const routeOptions = ROUTES.map(formatRouteOption);
+            const selectedOption = await promptSelect("Choose your next journey:", routeOptions);
+            const selectedRoute = ROUTES[routeOptions.indexOf(selectedOption)];
+            config.journey = {
+                route_id: selectedRoute.id,
+                started_at: new Date().toISOString().slice(0, 19),
+                started_km: totalKm,
+                completed_routes: completedRoutes,
+            };
+            await saveConfig(config);
+            consola.success(`New journey: ${selectedRoute.from} \u2192 ${selectedRoute.to} (${selectedRoute.total_km.toLocaleString()} km)`);
+        }
+        // Git sync result
+        const gitResult = await gitSync;
+        switch (gitResult) {
+            case "pushed":
+                consola.success("Pushed to GitHub.");
+                break;
+            case "push-failed":
+                consola.warn("Push failed. Run `stp sync` to retry.");
+                break;
+            case "commit-failed":
+                consola.warn("Commit failed. Run `stp sync` later.");
+                break;
+        }
+    },
+});

package/dist/commands/config.js

@@ -0,0 +1,92 @@
+import { defineCommand } from "citty";
+import { consola } from "consola";
+import { loadConfig, saveConfig, getCsvPath } from "../lib/config.js";
+import { readRecords } from "../lib/csv.js";
+import { ROUTES, formatRouteOption } from "../lib/routes.js";
+import { promptSelect, promptConfirm } from "../lib/prompt.js";
+export const configCommand = defineCommand({
+    meta: { name: "config", description: "Update configuration" },
+    args: {
+        key: {
+            type: "positional",
+            description: "Config key (speed, weight, route)",
+            required: true,
+        },
+        value: {
+            type: "positional",
+            description: "New value (not needed for route)",
+            required: false,
+        },
+    },
+    run: async ({ args }) => {
+        const config = await loadConfig();
+        switch (args.key) {
+            case "speed": {
+                if (!args.value) {
+                    consola.error("Usage: stp config speed <value>");
+                    process.exit(1);
+                }
+                const speed = parseFloat(args.value);
+                if (isNaN(speed) || speed <= 0) {
+                    consola.error("Invalid speed. Provide a positive number.");
+                    process.exit(1);
+                }
+                config.default_speed = speed;
+                await saveConfig(config);
+                consola.success(`Default speed updated to ${speed} km/h`);
+                break;
+            }
+            case "weight": {
+                if (!args.value) {
+                    consola.error("Usage: stp config weight <value|none>");
+                    process.exit(1);
+                }
+                if (args.value === "none" || args.value === "null" || args.value === "0") {
+                    config.weight_kg = null;
+                    await saveConfig(config);
+                    consola.success("Weight cleared.");
+                    break;
+                }
+                const weight = parseFloat(args.value);
+                if (isNaN(weight) || weight <= 0) {
+                    consola.error("Invalid weight. Provide a positive number, or 'none' to clear.");
+                    process.exit(1);
+                }
+                config.weight_kg = weight;
+                await saveConfig(config);
+                consola.success(`Weight updated to ${weight} kg`);
+                break;
+            }
+            case "route": {
+                if (config.journey) {
+                    const currentRoute = ROUTES.find((r) => r.id === config.journey.route_id);
+                    if (currentRoute) {
+                        consola.info(`Current route: ${currentRoute.from} \u2192 ${currentRoute.to}`);
+                    }
+                    const confirmed = await promptConfirm("Changing route will reset your journey progress. Continue?", false);
+                    if (!confirmed) {
+                        consola.info("Cancelled.");
+                        return;
+                    }
+                }
+                const routeOptions = ROUTES.map(formatRouteOption);
+                const selectedOption = await promptSelect("Choose your journey:", routeOptions);
+                const selectedRoute = ROUTES[routeOptions.indexOf(selectedOption)];
+                const records = await readRecords(getCsvPath(config));
+                const totalKm = records.reduce((s, r) => s + r.distance_km, 0);
+                config.journey = {
+                    route_id: selectedRoute.id,
+                    started_at: new Date().toISOString().slice(0, 19),
+                    started_km: totalKm,
+                    completed_routes: config.journey?.completed_routes ?? [],
+                };
+                await saveConfig(config);
+                consola.success(`Journey set: ${selectedRoute.from} \u2192 ${selectedRoute.to} (${selectedRoute.total_km.toLocaleString()} km)`);
+                break;
+            }
+            default:
+                consola.error(`Unknown config key: "${args.key}". Available: speed, weight, route`);
+                process.exit(1);
+        }
+    },
+});