pan-stack-cli 0.1.5 → 0.2.2

package/README.md

@@ -1,217 +1,71 @@
 # pan-stack-cli
 
-Global CLI for PAN Stack workspaces. Install once, use in any project that has
-`.project.yaml`.
+Global CLI for PAN Stack workspaces (`pan`). Cài một lần, dùng mọi project có `.project.yaml`.
+
+> **Tài liệu:** [docs/README.md](./docs/README.md) — overview, kiến trúc, tra lệnh đầy đủ.
+> Planning: `btp-csdl-cc/docs/projects/PANCLI/`.
 
 ```bash
 npm i -g pan-stack-cli
-# or from source before npm publish:
-npm i -g /path/to/pan-stack-cli
+# hoặc từ source:
+npm i -g /path/to/apps/pan-stack-tools/pan-stack-cli
 ```
 
-## What is PAN Stack?
-
-PAN Stack is a **workspace shell** for coding with AI agents — not a monorepo that
-contains every product repository. The stack repo holds:
-
-- Agent skills and prompts (`.claude`, `.cursor`, `.codex`)
-- Workspace manifests (`.project.yaml`, `.pan.yaml`)
-- Team docs and coordination files
-
-Product source code lives in separate repositories listed in `.project.yaml`. The
-`pan` CLI ties them together: clone all repos, run git ops across the workspace,
-and execute project commands defined in `.pan.yaml`.
+## PAN Stack là gì?
 
-```text
-bookshop-stack/                 # PAN Stack workspace (shell)
-  .project.yaml                 # Which repos belong to this workspace
-  .pan.yaml                     # Workspace-level pan commands
-  .claude/skills/               # Claude Code skills
-  .cursor/skills/               # Cursor agent skills
-  .codex/skills/                # Codex agent skills
-  apps/
-    web/                        # bookshop-web (cloned product repo)
-    api/                        # bookshop-api (cloned product repo)
-```
+Lớp **điều phối** AI agent stack — skills, manifest, lệnh workspace — **không** chứa toàn bộ source sản phẩm. Repo sản phẩm liệt kê trong `.project.yaml`; `pan clone` kéo về `apps/`.
 
-Run `pan create` to scaffold this layout with the shared `writing-guidelines`
-skill pre-installed for all three agent folders.
-
-## Requirements
+## Yêu cầu
 
 - Node.js 18+
-- Git (for `pan clone`, `pull`, `sync-main`, `fetch`, `push`, `grv`, `gst`)
-
-## Windows support
+- Git (Git for Windows + bash cho lệnh `shell:` trong `.pan.yaml`)
 
-Built-in commands (`create`, `clone`, `pull`, `sync-main`, `push`, `fetch`, `grv`, `gst`) run on
-Windows, macOS, and Linux. Notes for Windows:
-
-- `shell:` blocks in `.pan.yaml` run through **bash** on all platforms (Git Bash on
-  Windows, system bash on macOS/Linux). Use `exec:` for simple one-liners (`npm test`)
-  when possible; those work without Bash.
-- Install **Git for Windows** if bash is not already on `PATH`.
-- Set `PAN_PROJECT_ROOTS` with **semicolon** separators (`C:\work\a;C:\work\b`).
-  Do not use `:` — it conflicts with drive letters.
-- Optional: set `PAN_GIT_BASH` to the full path of `bash.exe` if Git is installed in
-  a non-standard location.
-
-## Bootstrap a new workspace
+## Bootstrap nhanh
 
 ```bash
 mkdir ~/work && cd ~/work
-pan create                    # prompts for folder name
-# or
-pan create bookshop-stack     # non-interactive
-
+pan create bookshop-stack
 cd bookshop-stack
-# Edit .project.yaml — replace repo_url_to_be_filled with real URLs
+# Sửa .project.yaml — URL repo thật
 pan clone
-pan install
 ```
 
-`pan create` fails if the target folder already exists.
-
-## Configuration files
+`pan create` cần **registry server** (`PAN_SKILL_REGISTRY_URL`, mặc định `http://localhost:4600`).
 
-Two files drive the CLI. Keep responsibilities separate:
+## Lệnh built-in (tóm tắt)
 
-| File | Role |
+| Nhóm | Lệnh |
 |------|------|
-| `.project.yaml` | Workspace manifest — lists `repositories` (name, url, path). **No commands.** |
-| `.pan.yaml` | `pan` commands — at workspace root and/or inside each child repo |
-
-### `.project.yaml` example
-
-```yaml
-project: bookshop-stack
-managed_by: your-team
-
-stack:
-  repo: https://github.com/example/bookshop-stack.git
-
-repositories:
-  - name: bookshop-web
-    description: Customer-facing web application
-    url: https://github.com/example/bookshop-web.git
-    path: apps/web
-  - name: bookshop-api
-    description: REST API service
-    url: https://github.com/example/bookshop-api.git
-    path: apps/api
-```
-
-### `.pan.yaml` — workspace root
-
-Orchestration commands. Paths are relative to the workspace root. Use
-`PAN_WORKSPACE_ROOT` in shell blocks:
-
-```yaml
-commands:
-  install:
-    alias: i
-    description: Install dependencies across cloned repositories
-    shell: |
-      set -euo pipefail
-      root="${PAN_WORKSPACE_ROOT}"
-      for dir in apps/web apps/api; do
-        [[ -d "$root/$dir" ]] || { echo "Missing: $root/$dir" >&2; exit 1; }
-        (cd "$root/$dir" && npm install)
-      done
-
-  test:
-    default: web
-    description: Run tests (web | api)
-    targets:
-      web:
-        cwd: apps/web
-        exec: npm test
-      api:
-        cwd: apps/api
-        exec: npm test
-```
+| Workspace | `create`, `language` / `lang` |
+| Git bulk | `clone`, `pull`, `push`, `fetch`, `checkout`, `mr`, `sync-main`, `gst`, `branch`, `grv` |
+| Git menu | `git` (TTY chọn lệnh) |
+| Agent | `ai`, `skills` |
+| Pan Studio | `ui` (login, clone, sync, …) |
+| Pan Plans | `plan`, `task`, `project`, `usecase`, `testcase`, `decision` |
+| Khác | `serve`, `stats`, `select` |
 
-### `.pan.yaml` — child repo
+Gõ `pan` không tham số (TTY) → menu chọn project → chọn lệnh.
 
-Place a `.pan.yaml` inside a cloned repo. `cwd` / `exec` are relative to that
-repo's root:
+**Tra cứu đầy đủ:** [docs/guides/cli-reference.md](./docs/guides/cli-reference.md) (~870 dòng — options, `.pan.yaml`, Pan Plans, Windows, …).
 
-```yaml
-commands:
-  dev:
-    description: Start local dev server
-    exec: npm run dev
+## Phát triển local
 
-  lint:
-    shell: |
-      set -euo pipefail
-      npm run lint
+```bash
+cd apps/pan-stack-tools/pan-stack-cli
+npm install
+npm test
+npm run build
+npm link   # hoặc npm i -g .
 ```
 
-Aliases: `alias: i` or `aliases: i, ins` (comma-separated).
-
-## Built-in git commands
-
-Read `repositories` from the nearest `.project.yaml` (walk-up from cwd):
-
-| Command | Action |
-|---------|--------|
-| `pan clone` | Clone all repositories in the manifest |
-| `pan pull` | Pull all cloned repositories |
-| `pan sync-main [repo\|all]` (`pan sm`) | Fetch + merge `origin/main` into current branch (interactive picker; conflict summary) |
-| `pan fetch` | Fetch all remotes |
-| `pan push` | Push all repos (`-u origin HEAD` by default) |
-| `pan grv` | `git remote -v` for workspace + each child repo |
-| `pan gst` | `git status` for workspace + each child repo |
-
-Git options:
-
-- `--base-dir DIR` — base for relative repo paths (default: directory containing `.project.yaml`)
-- `--dry-run` — print commands only
-- `[manifest]` — manifest path (default: `.project.yaml`)
-
-Works from child repo directories — the CLI walks up to find `.project.yaml`.
-
-## Project commands
-
-The CLI loads **all** `.pan.yaml` files in the workspace (root + each
-`repositories[].path`). When the same command name appears in multiple repos,
-use `--project <name>` or pick interactively.
-
-### Environment variables
-
-| Variable | Meaning |
-|----------|---------|
-| `PAN_WORKSPACE_ROOT` | Directory containing `.project.yaml` |
-| `PAN_REPO_ROOT` | Directory containing the active `.pan.yaml` |
-| `PAN_PROJECT_ROOT` | Alias of `PAN_WORKSPACE_ROOT` |
-| `PAN_ARG_1`, … | Arguments after the command name |
-
-### Registry (optional)
-
-- `PAN_PROJECT_ROOTS` — extra workspace roots (`;` on Windows, `:` or `;` on Unix)
-- `~/.pan/projects` — one workspace root per line
+Chi tiết: [docs/how-to/npm-development.md](./docs/how-to/npm-development.md) · [docs/how-to/npm-release.md](./docs/how-to/npm-release.md).
 
 ## Package layout
 
 ```text
 pan-stack-cli/
-  bin/pan.js              # CLI entry
-  lib/
-    create.js             # pan create scaffold
-    discover.js             # workspace discovery
-    platform.js             # Windows/cross-platform helpers
-    manifest.js             # YAML parsing
-    run-command.js        # command execution
-    git/                  # clone, pull, sync-main, push, fetch, grv, gst
-  templates/workspace/    # pan create template
-  references/             # npm publish docs
+├── bin/pan.js              # bundle (esbuild)
+├── tools/pan-stack-cli/    # core CLI source
+├── tools/pan-stack-plan/   # Pan Plans
+└── docs/                   # tài liệu
 ```
-
-## Local development
-
-Install globally from source: [references/npm-development.md](references/npm-development.md).
-
-## Publish to npm
-
-See [references/npm-release.md](references/npm-release.md).