codekanban 0.31.0 → 0.32.0

package/README.md

@@ -51,6 +51,28 @@ codekanban
 - **📝 Notes**
   Multi-tab notes for quick recording of ideas and issues (Hotkey: `1`).
 
+
+## Installable Codex Skill Bundle
+
+This repository ships an installable Codex skill bundle built around a single public CLI: `codekanban-cli`.
+Use it when you want the CodeKanban skill workflow on another machine without copying the full repository.
+
+JavaScript package layout:
+
+- `packages/node-sdk`: library-only SDK for JS integrations
+- `packages/codekanban-cli`: the only public CLI and the owner of the packaged Codex skills
+- `packages/codekanban-cli/skills/codekanban-cli`: the single shipped Codex skill source
+
+Key defaults:
+
+- Default service URL: `http://127.0.0.1:3007`
+- First-time auth setup: `printf '%s' '<PASSWORD>' | codekanban-cli auth save-token --password-stdin`
+- Non-default service URL: `codekanban-cli --base-url http://192.168.1.50:3007 session list --path /repo`
+- Saved auth file: Windows `%APPDATA%\codekanban-cli\session.json`; macOS/Linux `$XDG_CONFIG_HOME/codekanban-cli/session.json` or `~/.config/codekanban-cli/session.json`
+
+The offline bundle installs one CLI package and copies one Codex skill.
+After installing the CLI and skills, restart Codex so the new skill is discovered.
+
 ## Development Guide
 
 ### Requirements

package/README.zh-CN.md

@@ -141,3 +141,18 @@ go build -ldflags="-s -w" -trimpath -o CodeKanban
 - 代码清理: 如前端的src/api，应当全走自动生成
 - 完成提醒功能，例如AI干完之后播放个声音，告诉你已经弄好了。
 - 空闲终端列表 / 待交互终端列表。
+
+
+## ???? Codex Skill Bundle
+
+????????? `codekanban-cli` ???? Codex skill bundle????????????????????????????
+
+??????
+
+- ???????`http://127.0.0.1:3007`
+- ????????`printf '%s' '<PASSWORD>' | codekanban-cli auth save-token --password-stdin`
+- ??????`codekanban-cli --base-url http://192.168.1.50:3007 session list --path /repo`
+- ????????Windows `%APPDATA%\codekanban-cli\session.json`?macOS/Linux `$XDG_CONFIG_HOME/codekanban-cli/session.json` ? `~/.config/codekanban-cli/session.json`
+
+?????????????????????????????????? `codekanban-cli`?
+??? CLI ? skills ?????? Codex ????????

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "codekanban",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "An auxiliary programming tool for the AI era, helping you speed up 10x.",
   "bin": {
     "codekanban": "npm-bin/codekanban.js"
   },
   "optionalDependencies": {
-    "@codekanban/win32-x64": "0.31.0",
-    "@codekanban/darwin-x64": "0.31.0",
-    "@codekanban/darwin-arm64": "0.31.0",
-    "@codekanban/linux-x64": "0.31.0",
-    "@codekanban/linux-arm64": "0.31.0"
+    "@codekanban/win32-x64": "0.32.0",
+    "@codekanban/darwin-x64": "0.32.0",
+    "@codekanban/darwin-arm64": "0.32.0",
+    "@codekanban/linux-x64": "0.32.0",
+    "@codekanban/linux-arm64": "0.32.0"
   },
   "keywords": [
     "ai",

package/packages/codekanban-cli/README.md

@@ -0,0 +1,118 @@
+# `@codekanban/cli`
+
+Installable CLI for operating CodeKanban workflows, sessions, and web sessions without keeping this repository on the target machine.
+
+`codekanban-cli` is the only public command surface. It builds on `@codekanban/sdk`, bundles that dependency for offline distribution, and ships its Codex skill sources from `skills/` inside this package.
+
+## Default behavior
+
+- Default server URL: `http://127.0.0.1:3007`
+- Base URL resolution order:
+  1. `--base-url`
+  2. `CODEKANBAN_BASE_URL` or `BASE_URL`
+  3. Saved user session file
+  4. `http://127.0.0.1:3007`
+- Token/password resolution order:
+  1. Explicit args such as `--token` or `--password`
+  2. `--token-file` / `--token-stdin` / `--password-file` / `--password-stdin`
+  3. `CODEKANBAN_TOKEN` / `TOKEN` / `CODEKANBAN_PASSWORD` / `PASSWORD`
+  4. Saved user session file for the matching base URL
+- Saved session file:
+  - Windows: `%APPDATA%\codekanban-cli\session.json`
+  - macOS/Linux: `$XDG_CONFIG_HOME/codekanban-cli/session.json` or `~/.config/codekanban-cli/session.json`
+
+## First-time setup
+
+If your CodeKanban server does not use password protection, you can start running commands immediately:
+
+```bash
+codekanban-cli project list
+```
+
+If password protection is enabled, save a token once and reuse it later:
+
+```bash
+printf '%s' 'your-password' | codekanban-cli auth save-token --password-stdin
+```
+
+You can also save a token directly:
+
+```bash
+codekanban-cli auth save-token --token-file ./token.txt --base-url http://127.0.0.1:3007
+```
+
+`auth save-token` validates the credential against the live server before writing:
+
+- `base_url`
+- `access_token`
+- `username`
+- `saved_at`
+
+## Project-aware commands
+
+List projects known to the target CodeKanban server:
+
+```bash
+codekanban-cli project list
+```
+
+Resolve a project by name:
+
+```bash
+codekanban-cli project resolve --project-name codekanban
+```
+
+If multiple candidates match, pick one directly without copying a project ID first:
+
+```bash
+codekanban-cli project resolve --project-name codekanban --project-index 2
+```
+
+Run a command directly against a project name:
+
+```bash
+codekanban-cli web-session create --project-name codekanban --agent codex --title "Planning session"
+codekanban-cli session list --project-name codekanban
+```
+
+If the service is local and you omit `--project-id`, `--project-name`, and `--path`, project-scoped commands fall back to the current working directory.
+If the service is remote, prefer `--project-id` or `--project-name`. In remote mode, `--path` means a server-side path on the machine running CodeKanban.
+
+## Common commands
+
+```bash
+codekanban-cli --help
+codekanban-cli auth status
+codekanban-cli project list
+codekanban-cli session list --project-name codekanban
+codekanban-cli web-session state --project-name codekanban --session-id <session-id>
+codekanban-cli web-session answer-pending --project-name codekanban --session-id <session-id>
+codekanban-cli web-session execute-plan --project-name codekanban --session-id <session-id>
+codekanban-cli web-session wait --project-name codekanban --session-id <session-id> --until done --settle-ms 2000
+codekanban-cli file read --project-name codekanban --file notes/123.md
+codekanban-cli web-session run --project-name codekanban --agent codex --text "Create a concise plan first, then implement it." --strict-cwd
+```
+
+If the service is not running on the default address, use either:
+
+```bash
+codekanban-cli --base-url http://192.168.1.50:3007 project list
+```
+
+or:
+
+```bash
+export CODEKANBAN_BASE_URL=http://192.168.1.50:3007
+codekanban-cli project list
+```
+
+## Available Codex skill
+
+- `codekanban-cli`: the shipped and discoverable Codex skill for operating CodeKanban through the installable CLI
+
+## Codex skills in this repo
+
+- Packaged skill source: `packages/codekanban-cli/skills/codekanban-cli`
+- Skill directory index: `packages/codekanban-cli/skills/README.md`
+- Release bundle builder: `packages/codekanban-cli/scripts/build-release-bundle.py`
+- Offline bundle install docs: `packages/codekanban-cli/release/README-install.md`

package/packages/codekanban-cli/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@codekanban/cli",
+  "version": "0.1.0",
+  "description": "Installable Codex skill CLI for operating CodeKanban workflows, sessions, and web sessions.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "codekanban-cli": "./bin/codekanban-cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "README.md"
+  ],
+  "dependencies": {
+    "@codekanban/sdk": "0.1.0"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "keywords": [
+    "codekanban",
+    "codex",
+    "skill",
+    "cli",
+    "web-session",
+    "workflow"
+  ],
+  "author": "fy0",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fy0/CodeKanban"
+  },
+  "homepage": "https://github.com/fy0/CodeKanban#readme",
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "pack:dry-run": "python scripts/pack_bundled_cli.py --dry-run",
+    "bundle:release": "python scripts/build-release-bundle.py"
+  },
+  "bundleDependencies": [
+    "@codekanban/sdk"
+  ]
+}

package/packages/codekanban-cli/release/install-cli-unix.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+
+npm install -g --no-fund --no-audit \
+  "$SCRIPT_DIR/npm/codekanban-cli-__CLI_VERSION__.tgz"
+
+echo "CLI install complete. Run ./install-skills-unix.sh as the real Codex user next."

package/packages/codekanban-cli/release/install-skills-unix.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+CODEX_HOME_DIR=${CODEX_HOME:-$HOME/.codex}
+SKILLS_DIR="$CODEX_HOME_DIR/skills"
+
+mkdir -p "$SKILLS_DIR"
+cp -R "$SCRIPT_DIR/skills/." "$SKILLS_DIR/"
+
+echo "Skills installed into $SKILLS_DIR"
+echo "Restart Codex to discover the new skills."

package/packages/codekanban-cli/release/install-unix.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env sh
+set -eu
+
+cat <<'EOF'
+Use the Unix install in two separate steps:
+
+  1. ./install-cli-unix.sh
+  2. ./install-skills-unix.sh
+
+Why split it?
+- Global npm installation can require sudo or a privileged prefix.
+- Skills must land in the real Codex user's ~/.codex/skills directory.
+- Running a combined sudo installer could put skills under root's ~/.codex/skills, which is the wrong account.
+
+After both steps finish, restart Codex.
+EOF

package/packages/codekanban-cli/release/install-windows.cmd

@@ -0,0 +1,19 @@
+@echo off
+setlocal enabledelayedexpansion
+set SCRIPT_DIR=%~dp0
+set BUNDLE_DIR=%SCRIPT_DIR%
+set CODEX_HOME_DIR=%CODEX_HOME%
+if "%CODEX_HOME_DIR%"=="" set CODEX_HOME_DIR=%USERPROFILE%\.codex
+set SKILLS_DIR=%CODEX_HOME_DIR%\skills
+
+echo Installing codekanban-cli from the offline bundle...
+call npm install -g --no-fund --no-audit "%BUNDLE_DIR%npm\codekanban-cli-__CLI_VERSION__.tgz"
+if errorlevel 1 exit /b 1
+
+echo Installing Codex skills into %SKILLS_DIR% ...
+if not exist "%SKILLS_DIR%" mkdir "%SKILLS_DIR%"
+xcopy /E /I /Y "%BUNDLE_DIR%skills\*" "%SKILLS_DIR%\" >nul
+if errorlevel 1 exit /b 1
+
+echo.
+echo Installation complete. Restart Codex to discover the new skills.

package/packages/codekanban-cli/skills/README.md

@@ -0,0 +1,18 @@
+# CodeKanban Codex skills
+
+This directory is the single source of truth for the Codex skills shipped with `@codekanban/cli`.
+
+Available skills in this package:
+
+- `codekanban-cli`: the primary discoverable skill for operating CodeKanban through the installable `codekanban-cli` command
+
+Key entrypoints:
+
+- Skill source: `packages/codekanban-cli/skills/codekanban-cli/SKILL.md`
+- Agent metadata: `packages/codekanban-cli/skills/codekanban-cli/agents/openai.yaml`
+
+Before using the skill:
+
+1. Install `codekanban-cli`
+2. Copy the `skills/` directory contents into the target user's Codex skills directory
+3. Restart Codex so the new skill is discovered

package/packages/codekanban-cli/skills/codekanban-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+schema_version: 1
+display_name: CodeKanban CLI
+short_description: Primary CodeKanban skill for project, web-session, workflow, session, and terminal control through the installable codekanban-cli command.
+default_prompt: Use codekanban-cli for CodeKanban project, web-session, workflow, session, and terminal control. If the user refers to a project by name, resolve it first with project list or project resolve, prefer web-session for structured work, use web-session run for the full answer-and-execute loop, and treat remote --path values as server-side paths.