strckro 0.0.0-stage → 0.3.0

package/DOCUMENTATION.md

@@ -0,0 +1,532 @@
+# Strckro CLI — เอกสารการใช้งาน
+
+เวอร์ชัน CLI: `0.3.0`  
+คำสั่ง: `skctl`  
+อัปเดตเอกสาร: 6 พฤศจิกายน 2026
+
+`skctl` เชื่อม Strckro เพื่อจัดการโปรเจค, Git sync, deployment, domain/TLS และ environment variables ผ่าน terminal ใช้ได้ทั้งคน, AI agents และ CI โดยไม่ต้องจัดการ HTTP, session cookie หรือ CSRF เอง
+
+## 1. สิ่งที่ต้องเตรียม
+
+- Node.js `20.20.2` ขึ้นไปบนเครื่องที่รัน CLI
+- Strckro backend ที่มี CLI API จากการพัฒนาชุดนี้ และบัญชีที่เข้าใช้งานได้
+- URL ของ Portal เช่น `https://portal.example.com`
+- Host ติดตั้ง Git และ runtime ที่โปรเจคต้องใช้ พร้อมตั้ง Git identity แล้ว
+
+CLI เชื่อมผ่าน HTTPS ยกเว้น HTTP บน `localhost`, `127.0.0.1` และ `[::1]` สำหรับพัฒนา URL ต้องเป็น origin เช่น `https://portal.example.com` ไม่มี path ต่อท้าย
+
+แพ็กเกจชื่อ `strckro` ติดตั้งผ่าน npm registry, ไฟล์ `.tgz` หรือ source ได้ การอัปเดต CLI อย่างเดียวไม่เพิ่ม API ให้ backend ที่ติดตั้งอยู่ ต้องอัปเดต backend ด้วย
+
+## 2. ติดตั้ง
+
+### ติดตั้งจาก npm registry
+
+```sh
+npm install --global strckro
+skctl --version
+skctl --help
+```
+
+อัปเดตเวอร์ชันล่าสุด:
+
+```sh
+npm install --global strckro@latest
+```
+
+ใช้ชั่วคราวโดยไม่ติดตั้ง global:
+
+```sh
+npx --package strckro skctl --help
+```
+
+### ติดตั้งจากไฟล์ npm package
+
+เครื่องที่มี source สร้างไฟล์สำหรับแจกได้ด้วย:
+
+```sh
+npm run pack:release
+```
+
+ส่ง `strckro-0.3.0.tgz` ไปยังเครื่องอื่นแล้วรัน:
+
+```sh
+npm install --global ./strckro-0.3.0.tgz
+skctl --version
+```
+
+การติดตั้งจาก `.tgz` ไม่ต้องรอ publish หรือ login บัญชี npm
+
+### Windows / PowerShell
+
+```powershell
+cd E:\dashboard-control-cli
+npm link
+skctl --version
+skctl --help
+```
+
+### Linux / macOS
+
+```sh
+cd /path/to/strckro
+npm link
+skctl --version
+```
+
+หากยังไม่ต้องการติดตั้งคำสั่ง global ให้รันจากโฟลเดอร์ CLI ด้วย:
+
+```sh
+node bin/skctl.mjs --help
+```
+
+## 3. เริ่มใช้งานอย่างรวดเร็ว
+
+ตัวอย่างนี้ใช้โปรเจค `my-app` ที่มีอยู่แล้วบน Portal:
+
+```sh
+skctl login --server https://portal.example.com
+skctl projects list --json
+skctl init --project my-app
+skctl env import --file .env.production
+skctl domains set --domains app.example.com
+skctl deploy --sync --wait --timeout 300 --json
+skctl domains verify --json
+```
+
+เปลี่ยน URL, project slug และ domain เป็นค่าของคุณเอง ก่อน verify domain ให้ตั้ง DNS ชี้มายัง server
+
+## 4. เข้าสู่ระบบ
+
+### 4.1 Login ผ่าน browser
+
+```sh
+skctl login --server https://portal.example.com
+```
+
+CLI แสดงรหัสกับลิงก์และเปิด browser ให้เข้า Portal ด้วยบัญชีเดิม ตรวจว่ารหัสตรงกับ terminal แล้วกด **อนุมัติ CLI** จากนั้น CLI จะรับ token และบันทึก credential บนเครื่อง
+
+คำขอ login มีอายุ 10 นาที ไม่ต้องเปิด localhost callback port และไม่ต้องกรอกรหัสผ่านบัญชีใน terminal
+
+### 4.2 Login โดยคัดลอกลิงก์เอง
+
+```sh
+skctl login --server https://portal.example.com --no-browser
+```
+
+CLI แสดงลิงก์โดยไม่เปิด browser ให้คัดลอกไปเปิดและอนุมัติเอง เหมาะกับ SSH หรือเครื่องที่ไม่มี browser โดย CLI จะรอรับผลผ่านการ polling
+
+### 4.3 Login ด้วย token จากหน้าเว็บ
+
+เข้า **Settings → Account → CLI และ AI access** บน Portal แล้วสร้าง token เลือกชื่อ, โปรเจค, สิทธิ์และอายุ จากนั้นนำค่าที่แสดงครั้งเดียวมาใช้:
+
+```sh
+skctl login --server https://portal.example.com --token YOUR_CLI_TOKEN
+```
+
+หากรับ token จาก secret manager ให้ส่งผ่าน stdin แทนการใส่ค่าใน command arguments:
+
+```sh
+secret-command | skctl login --server https://portal.example.com --token-stdin
+```
+
+`secret-command` ในตัวอย่างหมายถึงคำสั่งอ่าน secret ของระบบที่คุณใช้อยู่
+
+### 4.4 จำกัดสิทธิ์ของการ login
+
+```sh
+skctl login --server https://portal.example.com --no-browser --project my-app --scope project.view,source.sync,deploy.start,logs.read --name "AI deploy" --days 7
+```
+
+| Option | ความหมาย |
+| --- | --- |
+| `--project SLUG` | จำกัด token ให้ใช้กับโปรเจคที่ระบุ ซึ่งต้องมีอยู่แล้ว |
+| `--scope SCOPE,...` | รายการสิทธิ์ คั่นด้วย comma |
+| `--name LABEL` | ชื่อที่แสดงในรายการ token |
+| `--days N` | อายุ 1–90 วัน ค่าเริ่มต้น 30 วัน |
+
+Browser login ค่าเริ่มต้นขอ scopes ที่ CLI รองรับทั้งหมด **ยกเว้น `env.read`** สมาชิกที่มีสิทธิ์น้อยกว่านั้นต้องระบุ `--scope` ให้ตรงกับสิทธิ์ของบัญชี
+
+### 4.5 ตรวจบัญชีและออกจากระบบ
+
+```sh
+skctl whoami --json
+skctl logout
+```
+
+`logout` ลบ credential ที่บันทึกไว้บนเครื่องนี้ การยกเลิก token ทุกสำเนาทำผ่านปุ่มถอนสิทธิ์บน Portal ส่วน `STRCKRO_TOKEN` ที่ตั้งใน environment ต้องล้างจาก environment แยกต่างหาก
+
+## 5. ตั้งค่า server และโปรเจค
+
+```sh
+skctl init --project my-app
+```
+
+คำสั่งตรวจว่าเข้าถึงโปรเจคได้แล้วสร้าง `strckro.json` ใน working directory:
+
+```json
+{
+  "server": "https://portal.example.com",
+  "project": "my-app"
+}
+```
+
+ไฟล์นี้ไม่มี token และสามารถ commit ให้ทีมใช้ร่วมกันได้ `init` จะไม่เขียนทับไฟล์เดิม CLI อ่านไฟล์จาก working directory ปัจจุบัน
+
+ลำดับเลือก server:
+
+1. `--server`
+2. `STRCKRO_SERVER`
+3. `server` ใน `strckro.json`
+4. Server ใน credential ที่บันทึกไว้
+
+ลำดับเลือกโปรเจค:
+
+1. `--project`
+2. Project slug ที่ระบุเป็น positional argument
+3. `STRCKRO_PROJECT`
+4. `project` ใน `strckro.json`
+
+Credential ที่บันทึกไว้จะใช้กับ server origin เดิมเท่านั้น สามารถใช้ `STRCKRO_TOKEN` สำหรับ CI โดยไม่บันทึก credential ลงเครื่อง
+
+**token ไปได้เฉพาะ server ที่คุณเลือกเอง:** `strckro.json` เป็นไฟล์ใน repository ซึ่งอาจมาจากคนอื่น (repo ที่ clone มา, fork ใน CI, repo ที่ AI agent เปิด) CLI จึงไม่ส่ง token ที่คุณให้ (`STRCKRO_TOKEN`, `login --token`, `login --token-stdin`) ไปยัง server ที่ระบุอยู่ใน `strckro.json` เพียงอย่างเดียว Token จะถูกส่งเมื่อ server มาจาก `--server`, `STRCKRO_SERVER` หรือเป็น origin เดียวกับที่ login ไว้บนเครื่องนี้ มิฉะนั้นคำสั่งจะหยุดด้วย exit 2 โดยยังไม่ส่งคำขอใดออกไป CI ที่ใช้ `STRCKRO_TOKEN` ให้ตั้ง `STRCKRO_SERVER` คู่กันเสมอ เช่นเดียวกับตัวอย่างในหัวข้อ CI
+
+## 6. สร้างและซิงก์โปรเจค
+
+### ดูรายการและสถานะ
+
+```sh
+skctl projects list
+skctl project my-app --info
+skctl project --info
+skctl projects list --json
+skctl project my-app --info --json
+```
+
+`projects list` แสดงเฉพาะ slug, ประเภทงาน (`web`/`worker`), runtime, deployment และ process หนึ่งบรรทัดต่อโปรเจค ไม่แสดง repository, release history หรือ logs ในรายการ
+
+`project [SLUG] --info` แสดงข้อมูลทีละโปรเจค: ชื่อ, source, branch/directory, sync, active/previous release, งาน deploy และ domains หากไม่ระบุ slug จะใช้ลำดับเลือกโปรเจคในหัวข้อ 5 ส่วน `project [SLUG]` แสดงตารางสรุปเฉพาะโปรเจคนั้น
+
+Deployment `active` แสดงสถานะ release ที่บันทึกไว้ ส่วน process เป็นผล runtime probe แยกกัน `unknown` หมายถึงยังยืนยันสถานะ process ไม่ได้ จึงไม่ควรใช้ deployment state เพียงอย่างเดียวสรุปว่าแอป healthy
+
+เติม `--json` เพื่อรับข้อมูล API ครบเหมือนเดิม รวม release history และ metadata ที่ token มีสิทธิ์อ่าน โดย stdout เป็น JSON object เดียว ไม่มีตารางหรือข้อความแนะนำ `skctl projects status [SLUG] --json` ยังคงใช้ได้ตามเดิม และให้โครงสร้างเดียวกับ `skctl project [SLUG] --info --json`
+
+### สร้างหรืออัปเดตจากไฟล์
+
+สร้าง `project.json` เช่น:
+
+```json
+{
+  "name": "My app",
+  "slug": "my-app",
+  "organizationId": "ORGANIZATION_ID_FROM_WHOAMI",
+  "repository": "https://github.com/your-org/your-app.git",
+  "branch": "main",
+  "directory": "/",
+  "runtime": "node",
+  "nodeMajor": 24,
+  "buildScript": "build",
+  "startScript": "start"
+}
+```
+
+```sh
+skctl whoami --json
+skctl projects sync --file project.json --json
+```
+
+ใช้ organization ID จากผล `whoami` หาก slug ยังไม่มีจะสร้างโปรเจค หากมีแล้วจะอัปเดต configuration และ sync source จึงควรตรวจเนื้อหาไฟล์ก่อนใช้กับโปรเจคเดิม
+
+Private repository ใช้ `credentialId` ของ Git credential ที่สร้างบน Portal ไว้แล้ว ส่วน runtime และฟิลด์เพิ่มเติมใช้ contract เดียวกับ `POST /api/projects/sync` ของ backend
+
+CLI deploy ใช้ Git source บน Portal ไม่อัปโหลด working directory จากเครื่องที่รัน CLI
+
+## 7. Deployment และ logs
+
+| งาน | คำสั่ง |
+| --- | --- |
+| Deploy source ที่ sync แล้ว | `skctl deploy my-app` |
+| Sync Git ก่อน deploy | `skctl deploy my-app --sync` |
+| รอผล deployment | `skctl deploy my-app --sync --wait --timeout 300` |
+| ดู job | `skctl jobs status JOB_ID --json` |
+| ดูประวัติ deployment | `skctl deployments list [SLUG] --json` |
+| อ่าน runtime logs | `skctl logs my-app --json` |
+| Restart | `skctl restart my-app` |
+| Rollback | `skctl rollback my-app --release RELEASE_ID` |
+
+`--wait` ใช้กับ `deploy` หากครบเวลาที่กำหนด CLI จะแจ้ง job ID ให้ตรวจต่อ การหยุดรอของ CLI ไม่ได้ยกเลิก deployment บน server
+
+หาก sync สร้าง deployment job ผ่าน auto-deploy แล้ว `deploy --sync` จะใช้ job นั้น โปรเจค web ต้องมี ENV อย่างน้อยหนึ่ง key ตาม validation ของ backend และการ deploy ยังคงผ่าน deployment queue/health checks เดิม
+
+## 8. Domain และ TLS
+
+```sh
+skctl domains list my-app --json
+skctl domains set my-app --domains app.example.com,www.example.com
+skctl domains check my-app --hostname app.example.com --json
+skctl domains verify my-app --json
+```
+
+`domains set` **แทนที่รายชื่อโดเมนทั้งหมด** ของโปรเจค ไม่ใช่เพิ่มโดเมนเดียวเข้าไปในรายการเดิม
+
+หากต้องการลบทั้งหมด:
+
+```sh
+skctl domains clear my-app --sync
+```
+
+`--sync` ใช้กับ `domains set` หรือ `domains clear` เพื่อเรียกการ sync เดิมของ Portal ส่วน `domains verify` ตรวจ DNS และเรียก workflow Nginx/TLS
+
+CLI จัดการ domain configuration บน Portal ไม่สร้าง DNS records ที่ผู้ให้บริการ DNS โหมด demo จะไม่ตั้ง Nginx/TLS จริง และเมื่อ backend ตอบ `ok:false` CLI จะ exit `1` พร้อมผลที่ตรวจต่อได้
+
+## 9. Environment variables
+
+### ดูชื่อ key และ revision
+
+```sh
+skctl env keys my-app --json
+```
+
+คำสั่งนี้ไม่คืนค่า secret ใช้สิทธิ์ `env.read` หรือ `env.write`
+
+### ตั้งค่า key เดียว
+
+```sh
+secret-command | skctl env set API_KEY my-app --stdin
+skctl env set API_KEY my-app --file ./secret.txt
+skctl env set OPTIONAL my-app --empty
+```
+
+เลือกเพียงหนึ่ง option ระหว่าง `--stdin`, `--file` และ `--empty` ค่าต้องอยู่บรรทัดเดียว โดย CLI ลบ newline ท้ายหนึ่งบรรทัดเมื่อรับผ่าน stdin/file
+
+### ลบ key
+
+```sh
+skctl env unset OLD_KEY my-app
+```
+
+### Import หลาย key
+
+ไฟล์ `.env.production` ตัวอย่าง:
+
+```dotenv
+NODE_ENV=production
+APP_NAME=My application
+OPTIONAL=
+```
+
+```sh
+skctl env import my-app --file .env.production --json
+```
+
+Import merge เฉพาะ keys ที่อยู่ในไฟล์ ไม่ลบ keys อื่นบน server
+
+### Export ค่าไปยังไฟล์
+
+```sh
+skctl env pull my-app --file .env.export
+```
+
+ต้องมี `env.read` แยกต่างหาก สร้างไฟล์ใหม่เท่านั้นและไม่พิมพ์ค่าลง stdout Token จาก default browser login ไม่มี scope นี้ ต้องเลือกเพิ่มเมื่อต้องการอ่านค่า
+
+### รูปแบบและการแก้พร้อมกัน
+
+- ชื่อ key ใช้ตัวพิมพ์ใหญ่ ตัวเลข และ underscore โดยเริ่มด้วยตัวอักษรหรือ underscore
+- Dotenv เป็น literal `KEY=value` บรรทัดเดียว ไม่ขยาย `$VARIABLE` หรือ shell expressions และรักษา quote ตามที่เขียน
+- ENV บน backend จำกัด 128 KB
+- การเขียนแก้เฉพาะ keys ที่ส่งและรักษา comment/keys อื่น
+- Backend ตรวจ revision ภายใน transaction หากมีคนแก้แทรกจะตอบ HTTP `412` / exit `5` โดย CLI ไม่ retry ทับอัตโนมัติ
+- ENV ที่บันทึกมีผลกับ deployment ครั้งถัดไป ไม่ deploy ให้อัตโนมัติจากคำสั่ง env
+
+ระบุ revision เองได้:
+
+```sh
+skctl env keys my-app --json
+skctl env set API_KEY my-app --file ./secret.txt --revision REVISION_FROM_KEYS
+```
+
+## 10. ใช้กับ AI agents และ CI
+
+AI ใช้ `skctl --help` เพื่อค้นคำสั่ง แล้วเติม `--json` เมื่อเรียก operation เพื่ออ่านผลได้แน่นอน ไม่ต้องต่อ API เอง
+
+ตัวอย่างคำสั่งงานที่ให้ AI:
+
+> ใช้ skctl ตรวจสถานะ my-app ด้วย --json จากนั้น import ENV จาก .env.production แล้ว deploy ด้วย --sync --wait --timeout 300 และรายงานผล job
+
+### PowerShell
+
+ตัวอย่างนี้สมมติว่า secret manager หรือ CI ฉีด `STRCKRO_TOKEN` ให้ process แล้ว:
+
+```powershell
+$env:STRCKRO_SERVER = 'https://portal.example.com'
+$env:STRCKRO_PROJECT = 'my-app'
+
+skctl projects status --json
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+skctl env import --file .env.production --json
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+skctl deploy --sync --wait --timeout 300 --json
+exit $LASTEXITCODE
+```
+
+### Bash
+
+```sh
+set -e
+export STRCKRO_SERVER=https://portal.example.com
+export STRCKRO_PROJECT=my-app
+# STRCKRO_TOKEN is injected by your CI secret store.
+
+skctl projects status --json
+skctl env import --file .env.production --json
+skctl deploy --sync --wait --timeout 300 --json
+```
+
+Operation ที่ใช้ `--json` คืน JSON object เดียวทาง stdout ลิงก์ login อยู่ stderr ส่วน `--help` และ `--version` เป็นข้อความ ไม่มีค่า ENV ในผลการเขียน
+
+ตัวอย่าง error JSON:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "CONFLICT",
+    "message": "Environment changed. Read the latest revision and retry.",
+    "status": 412
+  }
+}
+```
+
+## 11. สิทธิ์ของ token
+
+Token ต้องผ่านทั้ง scope ของ token และสิทธิ์ปัจจุบันของบัญชีในองค์กรนั้น การปิดบัญชี เปลี่ยนรหัสผ่าน ถอน token หรือ token หมดอายุทำให้ใช้งานไม่ได้ การถอนสิทธิ์องค์กรมีผลกับ request ถัดไปและตรวจซ้ำก่อน mutation commit
+
+| Scope | ใช้ทำอะไร |
+| --- | --- |
+| `project.view` | ดูรายการและสถานะโปรเจค |
+| `project.create` | สร้างโปรเจคผ่าน sync |
+| `project.configure` | เปลี่ยน configuration ของโปรเจคเดิมผ่าน sync |
+| `source.sync` | Sync source ของโปรเจคเดิม |
+| `deploy.start` | Deploy หรือ restart |
+| `deploy.rollback` | Rollback |
+| `domains.manage` | ตั้งค่า ตรวจและ verify domain |
+| `env.read` | อ่านค่า ENV และ export |
+| `env.write` | แก้ ENV และอ่าน metadata/revision |
+| `logs.read` | อ่าน runtime logs และ deployment jobs |
+| `credentials.use` | ผูกหรือเปลี่ยน Git credential ที่ใช้ sync |
+
+Token ไม่สามารถจัดการบัญชี/สิทธิ์ผู้ใช้ ออก token ต่อ จัดการ Git credentials หรือติดตั้ง host tools ส่วน Monitor token เดิมยังคงอ่านอย่างเดียวและใช้แทน CLI token ไม่ได้
+
+## 12. Config และการเก็บ credential
+
+| Environment variable | ความหมาย |
+| --- | --- |
+| `STRCKRO_SERVER` | Origin ของ Portal |
+| `STRCKRO_TOKEN` | Token สำหรับ process/CI โดยไม่ต้อง login บันทึกลงเครื่อง ใช้คู่กับ `STRCKRO_SERVER` หรือ `--server` (ไม่ส่งไปยัง server ที่มาจาก `strckro.json` อย่างเดียว) |
+| `STRCKRO_PROJECT` | Default project slug |
+| `STRCKRO_CONFIG_DIR` | เปลี่ยนโฟลเดอร์เก็บ credential |
+| `XDG_CONFIG_HOME` | Base config directory หากไม่ได้กำหนด `STRCKRO_CONFIG_DIR` |
+
+ค่าเริ่มต้นอยู่ที่ `$XDG_CONFIG_HOME/strckro/credentials.json` หรือ `~/.config/strckro/credentials.json`
+
+Windows เข้ารหัส token ด้วย DPAPI ผูกกับ OS user ปัจจุบัน ส่วน Linux/macOS เก็บไฟล์สิทธิ์ `0600` ในโฟลเดอร์ที่สร้างด้วยสิทธิ์ `0700` Server เก็บเฉพาะ hash ของ token/device secret และ ENV ยังคงเข้ารหัสด้วย vault ของ Portal
+
+## 13. Global options และ exit codes
+
+| Option | ความหมาย |
+| --- | --- |
+| `--server URL` | เลือก Portal origin |
+| `--project SLUG` | เลือกโปรเจค |
+| `--json` | คืน operation result เป็น JSON |
+| `--timeout SECONDS` | Request timeout 1–3600 วินาที ค่าเริ่มต้น 30; ใช้เป็นเวลารอ deploy เมื่อมี `--wait` ด้วย |
+| `--help` | แสดงคำสั่ง |
+| `--version` | แสดงเวอร์ชัน CLI |
+
+| Exit code | ความหมาย |
+| --- | --- |
+| `0` | สำเร็จ |
+| `1` | API หรือ deployment ไม่สำเร็จ รวม HTTP สำเร็จที่มี `ok:false` |
+| `2` | Input, option หรือ configuration ไม่ถูกต้อง |
+| `3` | ไม่มี credential หรือ token ใช้ไม่ได้ |
+| `4` | ไม่มีสิทธิ์ |
+| `5` | ENV revision เปลี่ยน |
+| `6` | Network error หรือรอ deployment จนครบเวลา |
+
+## 14. แก้ปัญหาเบื้องต้น
+
+| อาการ | วิธีตรวจ |
+| --- | --- |
+| หา `skctl` ไม่พบ | รัน `npm link` ในโฟลเดอร์ CLI และตรวจ npm global bin ใน PATH |
+| Login พบ endpoint 404 | ตรวจ URL และอัปเดต backend ให้มี CLI API |
+| Exit 3 | ตรวจ `STRCKRO_TOKEN`, วันหมดอายุ/การถอน token หรือ login ใหม่ |
+| Exit 4 | ตรวจ scope ของ token และสิทธิ์บัญชีในองค์กร/โปรเจค |
+| ENV pull ไม่ได้ แต่เขียนได้ | เพิ่ม `env.read` ใน token และตรวจสิทธิ์บัญชี |
+| Exit 5 | อ่าน keys/revision ใหม่ ตรวจการเปลี่ยนแปลง แล้วค่อยส่งการแก้อีกครั้ง |
+| Deploy แจ้งให้ sync ก่อน | ใช้ `deploy --sync` หรือ `projects sync --file project.json` |
+| Domain verify ยัง pending | ตรวจ DNS, การ deploy และความพร้อมของ Nginx/TLS บน host |
+| Export/init แจ้งไฟล์มีอยู่แล้ว | เลือก path ใหม่ หรือจัดการไฟล์เดิมก่อน คำสั่งไม่เขียนทับให้อัตโนมัติ |
+
+## 15. API สำหรับผู้พัฒนาต่อ
+
+CLI เรียก backend เป็นผู้ตรวจสิทธิ์ บันทึก เข้ารหัส และ audit ส่วน client ดูแล input, credential และ output
+
+| Method | Endpoint | Authentication |
+| --- | --- | --- |
+| `POST` | `/api/cli/device/start` | Anonymous, จำกัดอัตราการสร้างคำขอ |
+| `POST` | `/api/cli/device/poll` | Device secret, polling interval 2 วินาที |
+| `GET`, `POST` | `/api/cli/devices/:userCode` | Browser session; POST ต้องมี CSRF |
+| `GET`, `POST` | `/api/cli/tokens` | Browser session; POST ต้องมี CSRF |
+| `DELETE` | `/api/cli/tokens/:id` | Browser session และ CSRF |
+| `GET` | `/api/access` | CLI bearer หรือ browser session |
+| `GET` | `/api/projects/:slug/environment/metadata` | Token scope/สิทธิ์ `env.read` หรือ `env.write` |
+| `PATCH` | `/api/projects/:slug/environment` | Token scope/สิทธิ์ `env.write` |
+
+Existing project endpoints รับ `Authorization: Bearer <CLI_TOKEN>` ผ่าน allow-list แยกตาม action โดย browser session ยังใช้การตรวจ CSRF เดิม
+
+ตัวอย่าง ENV patch body:
+
+```json
+{
+  "revision": "REVISION_FROM_METADATA",
+  "set": {
+    "APP_NAME": "My app",
+    "OPTIONAL": ""
+  },
+  "unset": ["OLD_KEY"]
+}
+```
+
+Backend ตรวจ revision และเขียนใน transaction เดียว การส่ง key ซ้ำระหว่าง `set` กับ `unset` จะถูกปฏิเสธ และ response ไม่คืนค่า secret ที่เขียน
+
+## 16. ทดสอบการพัฒนา
+
+### การย้ายจาก CLI เดิม
+
+แพ็กเกจใหม่คือ `strckro` คำสั่ง `skctl` มี alias `strckro` ใช้แทนกันได้ ยังคงรองรับตัวแปร `DASHBOARD_*` แต่ `STRCKRO_*` จะมีลำดับสูงกว่า อ่าน `dpctl.json` เมื่อไม่มี `strckro.json` และอ่าน credential เก่าในโฟลเดอร์ `dpctl` เมื่อไม่มี config override การ login ใหม่บันทึกในโฟลเดอร์ `strckro`; logout ล้าง credential default ทั้งสองที่
+
+### CLI
+
+```powershell
+cd E:\dashboard-control-cli
+npm test
+```
+
+### ทดสอบ CLI คู่กับ backend
+
+```powershell
+$env:DASHBOARD_BACKEND_PATH = 'E:\dashboard-control'
+npm test
+```
+
+เมื่อไม่กำหนด `DASHBOARD_BACKEND_PATH` จะข้าม paired integration test
+
+### Backend
+
+```powershell
+cd E:\dashboard-control
+node --test test/cli-api.test.mjs
+npm run docs:check
+```
+
+Integration tests ใช้ backend โหมด demo ไม่ได้รับรอง deployment, DNS, Nginx หรือการออก TLS จริงบน production Linux

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dashboard Portal contributors
+
+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/PUBLISHING.md

@@ -0,0 +1,66 @@
+# เผยแพร่ Strckro CLI บน npm
+
+ชื่อแพ็กเกจ: `strckro`  
+คำสั่งหลังติดตั้ง: `skctl`  
+Registry: `https://registry.npmjs.org/`  
+การเข้าถึง: public
+
+รุ่น 0.3.0 เปลี่ยน `projects list` เป็นตารางสรุปหนึ่งบรรทัดต่อโปรเจค เพิ่ม `project [SLUG] --info` สำหรับเจาะรายละเอียด และคงข้อมูล `--json` กับคำสั่ง `projects status` เดิมไว้
+
+## ตรวจแพ็กเกจก่อนเผยแพร่
+
+```sh
+npm ci
+npm test
+npm run test:package
+npm publish --dry-run
+```
+
+`test:package` สร้าง tarball จริง ตรวจว่าไฟล์ตรงกับ allow-list แล้วติดตั้งด้วย npm ใน global prefix ชั่วคราว ทดสอบ launcher `skctl --version` และ help จาก working directory อื่น โดยไม่แก้ credential หรือ CLI ที่ติดตั้งแบบ global ของผู้ใช้
+
+แพ็กเกจมีเฉพาะ runtime, `README.md`, `DOCUMENTATION.md`, `PUBLISHING.md`, `LICENSE` และ `package.json` ไม่รวม tests, scripts, `.env`, `.npmrc`, token หรือ local project configuration
+
+`prepublishOnly` รัน tests และ package smoke อีกครั้งก่อน publish ส่วนเวอร์ชันที่ CLI แสดงอ่านจาก `package.json` โดยตรง
+
+## Login และ publish
+
+```sh
+npm login --auth-type=web --registry=https://registry.npmjs.org/
+npm whoami --registry=https://registry.npmjs.org/
+npm run publish:npm
+```
+
+ทำ browser login และการยืนยัน 2FA ตามที่ npm แสดง ไม่ต้องใส่ password, token หรือรหัส 2FA ลง source หรือส่งให้ผู้อื่น บัญชีที่ publish ต้องมีสิทธิ์ในชื่อแพ็กเกจนี้ หาก npm ไม่ให้ใช้ชื่อดังกล่าว ให้เลือกชื่อใหม่แล้วตรวจ package อีกครั้ง
+
+เมื่อตีพิมพ์ `name@version` สำเร็จแล้วไม่สามารถนำเวอร์ชันเดิมมาตีพิมพ์ซ้ำได้ สำหรับ release ถัดไป:
+
+```sh
+npm version patch --no-git-tag-version
+npm run publish:npm
+```
+
+## ตรวจจาก registry หลัง publish
+
+```sh
+npm view strckro version
+npm install --global strckro
+skctl --version
+```
+
+เครื่องอื่นติดตั้งได้ด้วย `npm install --global strckro` หรือใช้ชั่วคราวด้วย `npx --package strckro skctl --help` หลัง publish สำเร็จ
+
+## แจก tarball โดยไม่ผ่าน registry
+
+```sh
+npm run pack:release
+```
+
+จะได้ `strckro-0.3.0.tgz` ตามเวอร์ชันปัจจุบัน ส่งไฟล์นี้ไปยังเครื่องอื่นแล้วติดตั้งได้ทันที:
+
+```sh
+npm install --global ./strckro-0.3.0.tgz
+skctl --version
+skctl login --server https://portal.example.com --no-browser
+```
+
+อ้างอิง: [npm publish](https://docs.npmjs.com/cli/v11/commands/npm-publish), [npm login](https://docs.npmjs.com/cli/v11/commands/npm-login)

package/README.md

@@ -1,3 +1,168 @@
-# Temporary Holding Version
+# Strckro CLI (`skctl`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CLI สำหรับคน, CI และ AI agents เชื่อม Strckro บน server ของคุณ ใช้ Node.js 20.20.2+ ไม่มี runtime dependencies
+
+## ติดตั้งผ่าน npm
+
+เครื่องอื่นติดตั้งผ่าน npm ได้ด้วย:
+
+```sh
+npm install --global strckro
+skctl --version
+skctl login --server https://portal.example.com --no-browser
+```
+
+หรือใช้ชั่วคราวโดยไม่ติดตั้ง global:
+
+```sh
+npx --package strckro skctl --help
+```
+
+หากต้องการแจกไฟล์แพ็กเกจโดยตรง สามารถสร้างและส่งไปติดตั้งบนเครื่องอื่นได้ด้วย:
+
+```sh
+npm run pack:release
+# On the other machine:
+npm install --global ./strckro-0.3.0.tgz
+```
+
+ดู [เอกสารฉบับเต็ม](DOCUMENTATION.md) และ [ขั้นตอน publish](PUBLISHING.md)
+
+## ติดตั้งจาก source
+
+```powershell
+cd E:\dashboard-control-cli
+npm link
+skctl --help
+```
+
+Linux/macOS ใช้ `npm link` ได้เช่นกัน Backend ต้องเป็น revision ที่มี CLI API ชุดนี้ก่อน
+
+## Login
+
+```sh
+skctl login --server https://portal.example.com
+skctl login --server https://portal.example.com --no-browser
+skctl login --server https://portal.example.com --token YOUR_CLI_TOKEN
+skctl whoami
+skctl logout
+```
+
+Browser login เปิด Settings > Account ให้ใช้บัญชีเดิม ตรวจรหัสตรงกับ terminal แล้วกดอนุมัติ ไม่ต้องกรอกรหัสผ่านใน CLI `--no-browser` แสดงลิงก์ให้คัดลอกเอง ใช้จาก SSH/เครื่องอื่นได้โดยไม่เปิด callback port คำขอมีอายุ 10 นาที
+
+สร้าง/ถอน token ใน **Settings > Account > CLI และ AI access** แสดงค่าครั้งเดียว จำกัดโปรเจค/scope ได้ อายุ 1–90 วัน (ค่าเริ่มต้น 30) บัญชีถูกปิดหรือเปลี่ยนรหัสผ่านจะใช้ token เดิมไม่ได้ สิทธิ์องค์กรตรวจใหม่ทุก request
+
+`--token` รองรับตามข้างบน หากไม่ต้องการ secret ใน shell history/process arguments ให้ใช้ `--token-stdin` หรือ `STRCKRO_TOKEN` ที่ฉีดจาก secret manager:
+
+```sh
+secret-command | skctl login --server https://portal.example.com --token-stdin
+```
+
+Windows เก็บ credential ด้วย DPAPI ผูกกับ OS user; Linux/macOS เก็บไฟล์ `0600` ในโฟลเดอร์ `0700` ใต้ `$XDG_CONFIG_HOME/strckro` หรือ `~/.config/strckro` เปลี่ยนด้วย `STRCKRO_CONFIG_DIR` ได้ HTTPS เท่านั้น ยกเว้น HTTP loopback เพื่อพัฒนา ไม่ตาม redirects และไม่ส่ง credential ที่บันทึกไว้ให้ origin อื่น `logout` ลบเฉพาะเครื่องนี้; ถอนที่หน้าเว็บเพื่อยกเลิกทุกสำเนา
+
+## โปรเจคและ deploy
+
+```sh
+skctl projects list
+skctl project my-app --info
+skctl init --project my-app
+skctl projects status --json
+skctl deployments list --json
+skctl projects sync --file project.json
+skctl env import --file .env.production
+skctl deploy --sync --wait --timeout 300
+skctl logs
+skctl restart
+skctl rollback --release RELEASE_ID
+skctl jobs status JOB_ID
+```
+
+`projects list` แสดงตารางหนึ่งบรรทัดต่อโปรเจค มี slug, ประเภทงาน, runtime และสถานะ deployment/process ดูรายละเอียดด้วย `project [SLUG] --info` หรือใช้โปรเจคจาก `--project`, environment และ `strckro.json` เมื่อไม่ระบุ slug `project [SLUG]` แสดงตารางเฉพาะโปรเจคนั้น `--json` ยังคงคืนข้อมูล API ครบสำหรับ AI/CI ทั้ง list และรายละเอียด และ `projects status [SLUG]` ยังใช้ได้ตามเดิม
+
+`init` สร้าง `strckro.json` เก็บแค่ server/project ไม่มี token ไม่เขียนทับไฟล์เดิม อาจ commit ให้ทีมใช้ร่วมกันได้ ลำดับเลือก server: `--server`, `STRCKRO_SERVER`, `strckro.json`, credential ที่บันทึก; project: `--project`, positional slug, `STRCKRO_PROJECT`, `strckro.json`
+
+`strckro.json` เป็นไฟล์ใน repository ที่อาจมาจากคนอื่น จึงไม่ถูกใช้เป็นปลายทางของ token ที่คุณให้เอง (`STRCKRO_TOKEN`, `login --token`, `--token-stdin`): token จะส่งเฉพาะเมื่อ server มาจาก `--server`, `STRCKRO_SERVER` หรือ origin ที่ login ไว้บนเครื่องนี้ มิฉะนั้นคำสั่งหยุดด้วย exit 2 โดยไม่ส่งคำขอ ใน CI ให้ตั้ง `STRCKRO_SERVER` คู่กับ `STRCKRO_TOKEN`
+
+สร้างโปรเจคด้วย `project.json` ตาม `POST /api/projects/sync` เช่น:
+
+```json
+{
+  "name": "My app",
+  "slug": "my-app",
+  "organizationId": "ID_FROM_WHOAMI",
+  "repository": "https://github.com/your-org/your-app.git",
+  "branch": "main",
+  "directory": "/",
+  "runtime": "node",
+  "nodeMajor": 24,
+  "startScript": "start",
+  "buildScript": "build"
+}
+```
+
+Deploy ใช้ Git source บน Portal ไม่อัปโหลด working directory; `--sync` ดึง source ก่อนและใช้ job จาก auto-deploy ถ้ามี Host ต้องติดตั้ง Git/runtime และตั้ง Git identity ตามปกติ Private repository ใช้ `credentialId` ที่สร้างบน Portal ไว้แล้ว runtime ต่าง ๆ ใช้ validation/deployment queue เดิม
+
+## Domain + TLS
+
+```sh
+skctl domains set --domains app.example.com,www.example.com
+skctl domains check --hostname app.example.com
+skctl domains verify
+skctl domains list
+skctl domains clear --sync
+```
+
+`set` แทนที่รายชื่อทั้งหมด `clear` ลบทั้งหมด `verify` ตรวจ DNS และเรียก Nginx/TLS workflow เดิม DNS ต้องชี้ server ก่อน CLI ไม่สร้าง records ที่ผู้ให้บริการ DNS โหมด demo ไม่ตั้ง Nginx/TLS จริง
+
+## Environment
+
+```sh
+skctl env keys
+secret-command | skctl env set API_KEY --stdin
+skctl env set API_KEY --file ./secret.txt
+skctl env set OPTIONAL --empty
+skctl env unset OLD_KEY
+skctl env import --file .env.production
+skctl env pull --file .env.export
+```
+
+`set/import` แก้เฉพาะ keys ที่ส่ง รักษา comment/keys อื่น `unset` ลบ key `--empty` ตั้งค่าว่าง ทุกครั้งเป็น atomic transaction และตรวจ revision ถ้ามีคนแก้แทรกจะ exit `5` ไม่ retry ทับอัตโนมัติ ส่ง `--revision REV` เพื่อกำหนด precondition เองได้ ENV มีผลเมื่อ deploy ครั้งถัดไป
+
+Dotenv ใช้ literal `KEY=value` บรรทัดเดียว ไม่ขยาย `$VARIABLE`/shell expressions รักษา quote ตามไฟล์ `set --stdin/--file` ลบ newline ท้ายหนึ่งบรรทัด Backend จำกัด ENV 128 KB `keys` ใช้ `env.read` หรือ `env.write`; เขียนใช้ `env.write`; `pull` ต้องมี `env.read` สร้างไฟล์ใหม่และไม่แสดงค่าลง stdout
+
+## AI / CI
+
+ให้ AI ใช้ `skctl --help` ค้นคำสั่ง และเติม `--json` stdout เป็น JSON object เดียว ส่วนลิงก์ login อยู่ stderr ไม่ต้องต่อ HTTP/cookie/CSRF เอง
+
+```sh
+export STRCKRO_SERVER=https://portal.example.com
+export STRCKRO_TOKEN="$(your-secret-manager read portal-token)"
+export STRCKRO_PROJECT=my-app
+skctl projects status --json
+skctl env import --file .env.production --json
+skctl deploy --sync --wait --timeout 300 --json
+```
+
+Browser login ค่าเริ่มต้นเปิด workflow โปรเจคทั้งหมด **ยกเว้น `env.read`** สมาชิกที่สิทธิ์น้อยกว่าให้เลือก scope ตรงกับสิทธิ์ เช่น:
+
+```sh
+skctl login --server https://portal.example.com --no-browser --project my-app --scope project.view,source.sync,deploy.start,logs.read
+```
+
+Scopes: `project.view`, `project.create`, `project.configure`, `source.sync`, `deploy.start`, `deploy.rollback`, `domains.manage`, `env.read`, `env.write`, `logs.read`, `credentials.use` token ไม่สามารถสร้าง token ต่อ/จัดการบัญชี/ติดตั้ง host tools/จัดการ Git credential
+
+## ย้ายจาก dashboard-control-cli
+
+แพ็กเกจใหม่ชื่อ `strckro` ใช้ `skctl` หรือ alias `strckro` แทน `dpctl` ตัวแปร `STRCKRO_*` มีลำดับสูงกว่า `DASHBOARD_*` เดิมที่ยังรองรับ อ่าน `dpctl.json` ได้เมื่อไม่มี `strckro.json` และอ่าน credential เก่าจาก config directory `dpctl` ได้เมื่อไม่มี override โฟลเดอร์ Login ครั้งถัดไปจะเก็บในโฟลเดอร์ `strckro` โดยยังใช้ DPAPI บน Windows
+
+Exit codes: `0` สำเร็จ, `1` API/deploy, `2` input, `3` authentication, `4` permission, `5` ENV conflict, `6` network/timeout JSON errors: `{ "ok": false, "error": { "code", "message", "status"? } }` HTTP สำเร็จแต่ `ok:false` จะคืนผลนั้นและ exit `1`
+
+## ทดสอบ
+
+```powershell
+npm test
+$env:DASHBOARD_BACKEND_PATH = 'E:\dashboard-control'
+npm test
+```
+
+กำหนด `DASHBOARD_BACKEND_PATH` เพื่อเพิ่ม integration tests กับ backend จริงในโหมด demo ซึ่งไม่รับรอง production Linux/Nginx/TLS

package/bin/skctl.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.mjs';
+process.exitCode = await run(process.argv.slice(2));

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "strckro",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Strckro deployment control plane CLI for people, CI, and AI agents",
+  "keywords": [
+    "strckro",
+    "cli",
+    "deployment",
+    "environment",
+    "domains",
+    "ai"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.20.2"
+  },
+  "bin": {
+    "skctl": "bin/skctl.mjs",
+    "strckro": "bin/skctl.mjs"
+  },
+  "files": [
+    "bin/skctl.mjs",
+    "src/cli.mjs",
+    "src/client.mjs",
+    "src/config.mjs",
+    "README.md",
+    "DOCUMENTATION.md",
+    "PUBLISHING.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:package": "node scripts/smoke-package.mjs",
+    "prepublishOnly": "node scripts/verify-release.mjs",
+    "pack:release": "npm pack",
+    "publish:npm": "npm publish --access public",
+    "start": "node bin/skctl.mjs"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,322 @@
+import { parseArgs, stripVTControlCharacters } from 'node:util';
+import { readFileSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { createClient, CliError } from './client.mjs';
+import { normalizeServer, readConfig, saveConfig, clearConfig, clientEnvironment } from './config.mjs';
+
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
+export const HELP = `skctl — Strckro CLI ${version}
+
+Authentication:
+  login --server URL [--no-browser] [--scope SCOPE,...] [--project SLUG]
+  login --server URL --token TOKEN       Use a token issued in Settings > Account
+  login --server URL --token-stdin       Read a token from stdin
+  whoami                                Check the current account
+  logout                                Remove this machine's saved credential
+
+Projects and deployment:
+  init --project SLUG                   Save server/project to ./strckro.json
+  projects list                        Compact project overview
+  project [SLUG] [--info]               Overview or details for one project
+  projects status [SLUG]
+  projects sync --file project.json      Create/update and sync a Git project
+  deployments list [SLUG]                List deployment history and active jobs
+  deploy [SLUG] [--sync] [--wait]         Deploy the synced Git revision
+  restart [SLUG]
+  rollback [SLUG] --release ID
+  jobs status ID
+  logs [SLUG]
+
+Domains:
+  domains list [SLUG]
+  domains set [SLUG] --domains a.com,b.com [--sync]
+  domains clear [SLUG]                   Remove all configured domains
+  domains check [SLUG] --hostname a.com
+  domains verify [SLUG]                  Verify DNS and apply Nginx/TLS
+
+Environment:
+  env keys [SLUG]                        Names and revision only
+  env set KEY [SLUG] --stdin|--file PATH|--empty
+  env unset KEY [SLUG]
+  env import [SLUG] --file .env           Merge keys atomically
+  env pull [SLUG] --file PATH            Export values; requires env.read
+
+Global options:
+  --server URL  --project SLUG  --json  --timeout SECONDS  --help
+  --scope SCOPE,...  --name LABEL  --days 1..90 (login)
+  --revision REV (env writes; otherwise fetch the current revision)
+
+Environment: STRCKRO_SERVER, STRCKRO_TOKEN, STRCKRO_PROJECT,
+             STRCKRO_CONFIG_DIR, XDG_CONFIG_HOME
+A token (STRCKRO_TOKEN or login --token) is sent only to --server, STRCKRO_SERVER
+or the server of your saved login, never to one named only by ./strckro.json.
+Legacy DASHBOARD_* variables and dpctl.json remain supported.
+Exit codes: 0 success; 1 API/deployment; 2 input; 3 authentication;
+            4 permission denied; 5 stale environment; 6 network/timeout.
+Deploy uses the repository configured on Portal; it does not upload local files.
+Use --json for AI/CI: stdout contains one JSON object; progress goes to stderr.
+`;
+
+const stringOptions = ['server', 'token', 'project', 'scope', 'name', 'days', 'file', 'domains', 'hostname', 'release', 'revision', 'timeout'];
+const booleanOptions = ['json', 'help', 'version', 'no-browser', 'token-stdin', 'stdin', 'empty', 'wait', 'sync', 'info'];
+const options = Object.fromEntries([...stringOptions.map(key => [key, { type: 'string' }]), ...booleanOptions.map(key => [key, { type: 'boolean' }])]);
+const slug = value => { if (!/^[a-z][a-z0-9-]{0,62}$/.test(value || '')) throw new CliError('Specify a valid project slug with --project or skctl init.'); return value; };
+const keyName = value => { if (!/^[A-Z_][A-Z0-9_]*$/.test(value || '')) throw new CliError('Specify an uppercase environment key.'); return value; };
+const required = (value, flag) => { if (!value) throw new CliError(`Provide ${flag}.`); return value; };
+
+// Keep each table entry on one line, even when a server field contains control characters.
+const display = value => stripVTControlCharacters(String(value ?? '')).replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ').replace(/\s+/g, ' ').trim() || '-';
+
+function projectList(projects) {
+  if (!projects.length) return 'No projects found.\n';
+  const rows = [
+    ['SLUG', 'TYPE', 'RUNTIME', 'DEPLOYMENT', 'PROCESS'],
+    ...projects.map(item => [item.slug, item.serviceType || 'web', item.runtime, item.deployment?.state, item.runtimeStatus?.state || 'unknown'].map(display))
+  ];
+  const widths = rows[0].map((_, index) => Math.max(...rows.map(row => row[index].length)));
+  return rows.map(row => row.map((value, index) => value.padEnd(widths[index])).join('  ').trimEnd()).join('\n')
+    + `\n\n${projects.length} project${projects.length === 1 ? '' : 's'}. Details: skctl project <slug> --info\n`;
+}
+
+function projectInfo(item) {
+  const rows = [
+    ['Name', item.name], ['Slug', item.slug], ['Type', item.serviceType || 'web'], ['Runtime', item.runtime],
+    ['Deployment', item.deployment?.state], ['Process', item.runtimeStatus?.state || 'unknown'],
+    ['Process checked', item.runtimeStatus?.checkedAt],
+    ['Active release', item.deployment?.activeReleaseId], ['Previous release', item.deployment?.previousReleaseId],
+    ['Deployment updated', item.deployment?.updatedAt],
+    ['Deploy job', item.deploymentProgress?.id], ['Job status', item.deploymentProgress?.status], ['Job phase', item.deploymentProgress?.phase],
+    ['Repository', item.repository], ['Branch', item.branch], ['Directory', item.directory],
+    ['Source sync', item.sync?.status], ['Source synced', item.sync?.at],
+    ['Domains', item.domains?.hosts?.join(', ') || '(none)']
+  ];
+  const width = Math.max(...rows.map(([label]) => label.length));
+  return rows.map(([label, value]) => `${label.padEnd(width)}  ${display(value)}`).join('\n')
+    + '\n\nUse --json for the complete project data.\n';
+}
+
+async function stdinText(input) {
+  if (input.isTTY) throw new CliError('Pipe the value into stdin.');
+  const chunks = []; let size = 0;
+  for await (const chunk of input) { size += Buffer.byteLength(chunk); if (size > 256 * 1024) throw new CliError('Input exceeds 256 KB.'); chunks.push(Buffer.from(chunk)); }
+  return Buffer.concat(chunks).toString('utf8');
+}
+function openBrowser(url) {
+  return new Promise(resolve => {
+    const command = process.platform === 'win32' ? ['rundll32.exe', ['url.dll,FileProtocolHandler', url]] : process.platform === 'darwin' ? ['open', [url]] : ['xdg-open', [url]];
+    const child = spawn(command[0], command[1], { detached: true, stdio: 'ignore', windowsHide: true });
+    child.once('error', () => resolve(false));
+    child.once('spawn', () => { child.unref(); resolve(true); });
+  });
+}
+async function localProject(cwd) {
+  for (const file of ['strckro.json', 'dpctl.json']) {
+    try { return JSON.parse(await readFile(resolve(cwd, file), 'utf8')); }
+    catch (error) { if (error.code === 'ENOENT') continue; throw new CliError(`Invalid ${file}.`); }
+  }
+  return {};
+}
+// Literal dotenv document: preserve quotes, never expand shell expressions.
+export function parseEnv(content) {
+  if (Buffer.byteLength(content) > 128 * 1024) throw new CliError('Environment file exceeds 128 KB.');
+  const result = Object.create(null);
+  for (const line of content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n').split('\n')) {
+    if (!line.trim() || line.trimStart().startsWith('#')) continue;
+    const match = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=(.*)$/);
+    if (!match || /[\r\0]/.test(line)) throw new CliError('Invalid environment file; use single-line KEY=value entries.');
+    if (Object.hasOwn(result, match[1])) throw new CliError(`Duplicate environment key: ${match[1]}.`);
+    result[match[1]] = match[2];
+  }
+  return result;
+}
+
+export async function run(argv, { env = process.env, cwd = process.cwd(), stdout = process.stdout, stderr = process.stderr, stdin = process.stdin, browser = openBrowser } = {}) {
+  env = clientEnvironment(env);
+  let json = argv.includes('--json');
+  const print = result => stdout.write(JSON.stringify(result, null, json ? 0 : 2) + '\n');
+  try {
+    let parsed;
+    try { parsed = parseArgs({ args: argv, options, allowPositionals: true, strict: true }); }
+    catch { throw new CliError('Unknown or incomplete option. Run skctl --help.'); }
+    const { values: flags, positionals: args } = parsed;
+    json = Boolean(flags.json);
+    if (flags.help || !args.length && !flags.version) { stdout.write(HELP); return 0; }
+    if (flags.version) { stdout.write(version + '\n'); return 0; }
+    const [command, action, ...rest] = args;
+    // Logout does not need a working server or credential decryption.
+    if (command === 'logout') { if (args.length !== 1) throw new CliError('Usage: skctl logout'); await clearConfig(env); print({ ok: true, message: 'Saved credential removed. Revoke it in Portal Settings > Account to invalidate it.' }); return 0; }
+    const supported = ['login', 'whoami', 'init', 'project', 'projects', 'deployments', 'deploy', 'restart', 'rollback', 'jobs', 'logs', 'domains', 'env'];
+    if (!supported.includes(command)) throw new CliError('Unknown command. Run skctl --help.');
+    const commandOptions = command === 'login' ? ['token', 'token-stdin', 'no-browser', 'scope', 'name', 'days']
+      : command === 'project' ? ['info']
+      : command === 'projects' && action === 'sync' ? ['file']
+      : command === 'deploy' ? ['sync', 'wait']
+      : command === 'rollback' ? ['release']
+      : command === 'domains' ? action === 'set' ? ['domains', 'sync'] : action === 'clear' ? ['sync'] : action === 'check' ? ['hostname'] : []
+      : command === 'env' ? action === 'set' ? ['stdin', 'file', 'empty', 'revision'] : action === 'unset' ? ['revision'] : action === 'import' ? ['file', 'revision'] : action === 'pull' ? ['file'] : [] : [];
+    for (const flag of Object.keys(flags)) if (!['server', 'project', 'json', 'timeout', 'help', 'version', ...commandOptions].includes(flag)) throw new CliError(`--${flag} does not apply to this command.`);
+    const local = await localProject(cwd);
+    const explicitServer = flags.server || env.DASHBOARD_SERVER;
+    const requestedServer = explicitServer || local.server;
+    const needsCredential = command !== 'login' && !env.DASHBOARD_TOKEN;
+    // A token the person supplies (STRCKRO_TOKEN, or login --token/--token-stdin) is a bearer
+    // secret, and a login, even by browser approval, ends by replacing the credential saved on this
+    // machine. strckro.json is repository content, possibly from a stranger, so it must not pick
+    // the server for either: only --server, STRCKRO_SERVER or the origin already logged in to on
+    // this machine may be trusted with them.
+    const needsTrustedServer = command === 'login' || Boolean(env.DASHBOARD_TOKEN);
+    let saved = !requestedServer || needsCredential || (needsTrustedServer && !explicitServer) ? await readConfig(env, { secret: false }) : {};
+    const server = normalizeServer(requestedServer || saved.server);
+    if (needsTrustedServer && !explicitServer && saved.server !== server) throw new CliError(`Refusing to use ${server}: that server comes only from strckro.json, which is repository content, so no token or login is sent there. Pass --server or set STRCKRO_SERVER to the Portal you trust.`);
+    if (needsCredential && saved.server === server) saved = await readConfig(env);
+    const timeout = flags.timeout === undefined ? 30 : Number(flags.timeout);
+    if (!Number.isFinite(timeout) || timeout < 1 || timeout > 3600) throw new CliError('Timeout must be 1–3600 seconds.');
+    let token = env.DASHBOARD_TOKEN || (saved.server === server ? saved.token : undefined);
+    let api = createClient({ server, token, timeout: timeout * 1000 });
+    const project = positional => slug(flags.project || positional || env.DASHBOARD_PROJECT || local.project);
+    const route = value => `/api/projects/${encodeURIComponent(value)}`;
+    if (command === 'login') {
+      if (args.length > 1) throw new CliError('Usage: skctl login --server URL');
+      if (flags.token && flags['token-stdin']) throw new CliError('Choose --token or --token-stdin.');
+      if (flags['token-stdin'] || flags.token || env.DASHBOARD_TOKEN) {
+        token = flags['token-stdin'] ? (await stdinText(stdin)).trim() : flags.token || env.DASHBOARD_TOKEN;
+      } else {
+        token = undefined;
+        const days = flags.days === undefined ? 30 : Number(flags.days);
+        if (!Number.isInteger(days) || days < 1 || days > 90) throw new CliError('Days must be 1–90.');
+        const device = await api('/api/cli/device/start', { method: 'POST', anonymous: true, body: { name: flags.name || `skctl @ ${hostname()}`, expiresInDays: days, ...(flags.scope ? { scopes: flags.scope.split(',') } : {}), ...(flags.project ? { projectSlug: slug(flags.project) } : {}) } });
+        const link = new URL(device.verificationPath, server);
+        if (link.origin !== server || link.pathname !== '/settings/account') throw new CliError('Invalid login URL returned by Portal.', 'INVALID_RESPONSE');
+        stderr.write(`Open this link and verify code ${device.userCode}:\n${link.href}\n`);
+        if (!flags['no-browser']) await browser(link.href);
+        const deadline = Date.now() + device.expiresIn * 1000;
+        let interval = Math.max(2, device.interval || 2);
+        while (Date.now() < deadline) {
+          await delay(interval * 1000);
+          let polled;
+          try { polled = await api('/api/cli/device/poll', { method: 'POST', anonymous: true, body: { deviceCode: device.deviceCode } }); }
+          catch (error) { if (error.status === 429) { interval = Math.min(10, interval + 2); continue; } throw error; }
+          if (polled.status === 'complete') { token = polled.token; break; }
+          if (polled.status !== 'pending') throw new CliError('Unexpected login response.', 'INVALID_RESPONSE');
+        }
+        if (!token) throw new CliError('Login expired. Run login again.', 'AUTH_REQUIRED', 401);
+      }
+      if (!/^dp_[A-Za-z0-9_-]{43}$/.test(token || '')) throw new CliError('Use a CLI token issued in Portal Settings > Account.');
+      api = createClient({ server, token, timeout: timeout * 1000 });
+      const identity = await api('/api/access');
+      await saveConfig({ server, token }, env);
+      print({ ok: true, server, user: identity.user });
+      return 0;
+    }
+    let result;
+    if (command === 'whoami') {
+      if (args.length !== 1) throw new CliError('Usage: skctl whoami');
+      result = { server, ...await api('/api/access') };
+    } else if (command === 'deployments') {
+      if (action !== 'list' || rest.length > 1) throw new CliError('Usage: skctl deployments list [SLUG]');
+      const target = flags.project || rest[0] || env.DASHBOARD_PROJECT || local.project;
+      result = await api('/api/deployments' + (target ? `?project=${encodeURIComponent(slug(target))}` : ''));
+    } else if (command === 'init') {
+      if (args.length !== 1) throw new CliError('Usage: skctl init --project SLUG');
+      const target = project();
+      const { projects } = await api('/api/projects');
+      if (!projects.some(item => item.slug === target)) throw new CliError('Project not found.', 'API_ERROR', 404);
+      await writeFile(resolve(cwd, 'strckro.json'), JSON.stringify({ server, project: target }, null, 2) + '\n', { flag: 'wx' });
+      result = { ok: true, server, project: target, file: resolve(cwd, 'strckro.json') };
+    } else if (command === 'project') {
+      if (args.length > 2) throw new CliError('Usage: skctl project [SLUG] [--info]');
+      const target = project(action);
+      const { projects } = await api('/api/projects');
+      result = { project: projects.find(item => item.slug === target) };
+      if (!result.project) throw new CliError('Project not found.', 'API_ERROR', 404);
+    } else if (command === 'projects') {
+      if (!['list', 'status', 'sync'].includes(action) || rest.length > (action === 'status' ? 1 : 0)) throw new CliError('Usage: skctl projects list|status [SLUG]|sync --file project.json');
+      if (action === 'sync') {
+        let body;
+        try { body = JSON.parse(await readFile(resolve(cwd, required(flags.file, '--file project.json')), 'utf8')); } catch (error) { if (error instanceof CliError) throw error; throw new CliError('Could not read project JSON file.'); }
+        if (!body || typeof body !== 'object' || Array.isArray(body)) throw new CliError('Project file must be a JSON object.');
+        slug(body.slug);
+        result = await api('/api/projects/sync', { method: 'POST', body });
+      } else {
+        result = await api('/api/projects');
+        if (action === 'status') { const target = project(rest[0]); result = { project: result.projects.find(item => item.slug === target) }; if (!result.project) throw new CliError('Project not found.', 'API_ERROR', 404); }
+      }
+    } else if (['deploy', 'restart', 'rollback', 'logs'].includes(command)) {
+      if (args.length > 2) throw new CliError(`Usage: skctl ${command} [SLUG]`);
+      const target = project(action);
+      if (flags.sync) {
+        if (command !== 'deploy') throw new CliError('--sync applies to deploy.');
+        const { projects } = await api('/api/projects');
+        const existing = projects.find(item => item.slug === target);
+        if (!existing) throw new CliError('Project not found.', 'API_ERROR', 404);
+        result = await api('/api/projects/sync', { method: 'POST', body: { ...existing, domains: existing.domains?.hosts } });
+      }
+      if (!(command === 'deploy' && result?.job)) result = await api(`${route(target)}/${command}`, command === 'logs' ? {} : { method: 'POST', body: command === 'rollback' ? { releaseId: required(flags.release, '--release ID') } : {} });
+      if (flags.wait && result.job) {
+        const deadline = Date.now() + timeout * 1000;
+        while (['queued', 'running'].includes(result.job.status)) {
+          if (Date.now() >= deadline) throw new CliError(`Deployment is still running. Check skctl jobs status ${result.job.id}.`, 'TIMEOUT');
+          await delay(1000);
+          const polled = await api(`/api/jobs/${encodeURIComponent(result.job.id)}`);
+          result = { ...result, job: polled.job };
+        }
+        if (result.job.status !== 'succeeded') throw new CliError(`Deployment ${result.job.status}. Check skctl jobs status ${result.job.id}.`, 'DEPLOYMENT_FAILED');
+      }
+    } else if (command === 'jobs') {
+      if (action !== 'status' || rest.length !== 1 || !/^[a-f0-9-]{36}$/i.test(rest[0])) throw new CliError('Usage: skctl jobs status ID');
+      result = await api(`/api/jobs/${encodeURIComponent(rest[0])}`);
+    } else if (command === 'domains') {
+      if (!['list', 'set', 'clear', 'check', 'verify'].includes(action) || rest.length > 1) throw new CliError('Usage: skctl domains list|set|clear|check|verify [SLUG]');
+      const target = project(rest[0]);
+      if (action === 'list') {
+        const { projects } = await api('/api/projects');
+        const item = projects.find(item => item.slug === target);
+        if (!item) throw new CliError('Project not found.', 'API_ERROR', 404);
+        result = { project: target, domains: item.domains ?? { hosts: [] } };
+      } else {
+        const endpoint = ['set', 'clear'].includes(action) ? 'domains' : `domains/${action}`;
+        const body = action === 'set' ? { domains: required(flags.domains, '--domains a.com,b.com').split(','), sync: Boolean(flags.sync) } : action === 'clear' ? { domains: [], sync: Boolean(flags.sync) } : action === 'check' ? { hostname: required(flags.hostname, '--hostname a.com') } : {};
+        result = await api(`${route(target)}/${endpoint}`, { method: 'POST', body });
+      }
+    } else if (command === 'env') {
+      if (!['keys', 'set', 'unset', 'import', 'pull'].includes(action) || rest.length > (['set', 'unset'].includes(action) ? 2 : 1)) throw new CliError('Usage: skctl env keys|set|unset|import|pull; see --help.');
+      const key = ['set', 'unset'].includes(action) ? keyName(rest[0]) : null;
+      const target = project(rest[key ? 1 : 0]);
+      const endpoint = `${route(target)}/environment`;
+      if (action === 'keys') result = await api(`${endpoint}/metadata`);
+      else if (action === 'pull') {
+        const file = resolve(cwd, required(flags.file, '--file PATH'));
+        const response = await api(endpoint);
+        await writeFile(file, response.environment.content, { flag: 'wx', mode: 0o600 });
+        result = { ok: true, file, keys: response.environment.variables.map(item => item.key) };
+      } else {
+        let set = {}, unset = [];
+        if (action === 'set') {
+          if ([flags.stdin, Boolean(flags.file), flags.empty].filter(Boolean).length !== 1) throw new CliError('Choose exactly one of --stdin, --file PATH, or --empty.');
+          const value = flags.empty ? '' : flags.stdin ? await stdinText(stdin) : await readFile(resolve(cwd, flags.file), 'utf8');
+          const cleaned = value.replace(/\r?\n$/, '');
+          if (/[\r\n\0]/.test(cleaned)) throw new CliError('Environment values must be single-line strings.');
+          set = { [key]: cleaned };
+        } else if (action === 'unset') unset = [key];
+        else { set = parseEnv(await readFile(resolve(cwd, required(flags.file, '--file .env')), 'utf8')); if (!Object.keys(set).length) throw new CliError('Environment file has no keys.'); }
+        const revision = flags.revision || (await api(`${endpoint}/metadata`)).environment.revision;
+        result = await api(endpoint, { method: 'PATCH', body: { revision, set, unset } });
+      }
+    }
+    if (!json && result?.ok !== false && command === 'projects' && action === 'list') stdout.write(projectList(result.projects));
+    else if (!json && result?.ok !== false && command === 'project') stdout.write(flags.info ? projectInfo(result.project) : projectList([result.project]));
+    else print({ ok: true, ...result });
+    return result?.ok === false ? 1 : 0;
+  } catch (error) {
+    const message = error instanceof CliError ? error.message : error.code === 'EEXIST' ? 'Output file already exists; choose a new path.' : error.code?.startsWith('E') ? 'Could not access the requested file or configuration.' : error.message || 'Command failed.';
+    const code = error instanceof CliError ? error.code : 'INVALID_INPUT';
+    if (json) print({ ok: false, error: { code, message, ...(error.status ? { status: error.status } : {}) } });
+    else stderr.write(`Error: ${message}\n`);
+    return error.status === 401 ? 3 : error.status === 403 ? 4 : error.status === 412 ? 5 : ['NETWORK_ERROR', 'TIMEOUT'].includes(code) ? 6 : code === 'INVALID_INPUT' ? 2 : 1;
+  }
+}

package/src/client.mjs

@@ -0,0 +1,16 @@
+export class CliError extends Error {
+  constructor(message, code = 'INVALID_INPUT', status) { super(message); this.code = code; this.status = status; }
+}
+export function createClient({ server, token, timeout = 30_000, fetchImpl = fetch }) {
+  return async (path, { method = 'GET', body, anonymous = false } = {}) => {
+    if (!anonymous && !token) throw new CliError('Run skctl login, or set STRCKRO_TOKEN.', 'AUTH_REQUIRED', 401);
+    let response;
+    try {
+      response = await fetchImpl(server + path, { method, redirect: 'error', signal: AbortSignal.timeout(timeout), headers: { accept: 'application/json', ...(body === undefined ? {} : { 'content-type': 'application/json' }), ...(!anonymous && token ? { authorization: `Bearer ${token}` } : {}) }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+    } catch { throw new CliError('Could not reach Portal. Check the server URL, TLS certificate, and network.', 'NETWORK_ERROR'); }
+    let result;
+    try { result = await response.json(); } catch { throw new CliError('Portal returned an invalid API response. Check server compatibility.', 'INVALID_RESPONSE', response.status); }
+    if (!response.ok) throw new CliError(result.error || `Portal returned HTTP ${response.status}.`, response.status === 401 ? 'AUTH_REQUIRED' : response.status === 403 ? 'FORBIDDEN' : response.status === 412 ? 'CONFLICT' : 'API_ERROR', response.status);
+    return result;
+  };
+}

package/src/config.mjs

@@ -0,0 +1,66 @@
+import { mkdir, readFile, rename, writeFile, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+
+export function normalizeServer(value) {
+  let url;
+  try { url = new URL(value); } catch { throw new Error('Set --server https://your-portal or STRCKRO_SERVER.'); }
+  if (url.username || url.password || url.search || url.hash || url.pathname !== '/') throw new Error('Server must be an origin, for example https://portal.example.com.');
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) throw new Error('HTTPS is required (HTTP is allowed only on loopback for local development).');
+  return url.origin;
+}
+export function configDirectory(env = process.env) {
+  return env.STRCKRO_CONFIG_DIR || env.DASHBOARD_CONFIG_DIR || join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'strckro');
+}
+export function clientEnvironment(env) {
+  return { ...env, ...Object.fromEntries(['SERVER', 'TOKEN', 'PROJECT', 'CONFIG_DIR'].map(key => [`DASHBOARD_${key}`, env[`STRCKRO_${key}`] ?? env[`DASHBOARD_${key}`]])) };
+}
+function legacyCredentialPath(env) {
+  if (env.STRCKRO_CONFIG_DIR || env.DASHBOARD_CONFIG_DIR) return null;
+  return join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'dpctl', 'credentials.json');
+}
+async function protect(value, decrypt = false) {
+  // DPAPI binds Windows credentials to the current OS user. The secret travels
+  // over stdin, never in command arguments, environment, or diagnostic output.
+  const expression = decrypt
+    ? '[Text.Encoding]::UTF8.GetString([Security.Cryptography.ProtectedData]::Unprotect([Convert]::FromBase64String($v), $null, [Security.Cryptography.DataProtectionScope]::CurrentUser))'
+    : '[Convert]::ToBase64String([Security.Cryptography.ProtectedData]::Protect([Text.Encoding]::UTF8.GetBytes($v), $null, [Security.Cryptography.DataProtectionScope]::CurrentUser))';
+  return new Promise((resolve, reject) => {
+    const child = spawn('powershell.exe', ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', `Add-Type -AssemblyName System.Security; $v = [Console]::In.ReadToEnd(); [Console]::Out.Write(${expression})`], { windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
+    let output = '';
+    child.stdout.on('data', chunk => { output += chunk; });
+    child.stderr.resume();
+    child.on('error', () => reject(new Error('Windows credential protection is unavailable. Use STRCKRO_TOKEN for this session.')));
+    child.on('close', code => code === 0 ? resolve(output) : reject(new Error('Could not access the Windows protected credential. Log in again.')));
+    child.stdin.on('error', () => {});
+    child.stdin.end(value);
+  });
+}
+export async function readConfig(env = process.env, { secret = true } = {}) {
+  let saved;
+  for (const path of [join(configDirectory(env), 'credentials.json'), legacyCredentialPath(env)].filter(Boolean)) {
+    try { saved = JSON.parse(await readFile(path, 'utf8')); break; }
+    catch (error) { if (error.code === 'ENOENT') continue; throw new Error('Could not read CLI credentials. Run login again.'); }
+  }
+  if (!saved) return {};
+  if (!secret) return { server: saved.server };
+  if (saved.storage === 'dpapi') saved.token = await protect(saved.token, true);
+  return saved;
+}
+export async function saveConfig({ server, token }, env = process.env) {
+  const directory = configDirectory(env);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const saved = process.platform === 'win32' ? { server, token: await protect(token), storage: 'dpapi' } : { server, token, storage: 'file' };
+  const temporary = join(directory, `credentials.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, JSON.stringify(saved) + '\n', { flag: 'wx', mode: 0o600 });
+    await rename(temporary, join(directory, 'credentials.json'));
+  } finally { await rm(temporary, { force: true }); }
+}
+export async function clearConfig(env = process.env) {
+  await rm(join(configDirectory(env), 'credentials.json'), { force: true });
+  const legacy = legacyCredentialPath(env);
+  if (legacy) await rm(legacy, { force: true });
+}