@miyaoka/fsss 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +117 -0
- package/package.json +4 -2
package/README.md
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# fsss
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@miyaoka/fsss)
|
|
4
|
+
[](https://www.npmjs.com/package/@miyaoka/fsss)
|
|
5
|
+
[](https://github.com/miyaoka/fsss/blob/main/LICENSE)
|
|
6
|
+
|
|
7
|
+
**fsss** — "File Structure, Single Schema" — bun + TypeScript + Zod
|
|
8
|
+
|
|
9
|
+
> ファイル構造がそのままコマンド構造になり、スキーマを一回書けば CLI フラグ・環境変数・設定ファイルのどこから値が来ても同じように型付きで受け取れる CLI フレームワーク
|
|
10
|
+
>
|
|
11
|
+
> _A CLI framework where your file structure becomes your command structure, and a single schema gives you typed values whether they come from flags, env vars, or config files._
|
|
12
|
+
|
|
13
|
+
## File Structure — ファイルを置くだけでコマンドが生える
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
commands/
|
|
17
|
+
serve.ts → my-app serve
|
|
18
|
+
config/
|
|
19
|
+
set.ts → my-app config set
|
|
20
|
+
get.ts → my-app config get
|
|
21
|
+
remote/
|
|
22
|
+
[name]/
|
|
23
|
+
push.ts → my-app remote origin push
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
ファイルを置くだけでコマンドが生える。ディレクトリのネストがサブコマンドの階層になる。`[name]` は動的セグメントで、`params.name` として値を受け取れる。
|
|
27
|
+
|
|
28
|
+
## Single Schema — 1つの定義で CLI / env / config を統合
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
// commands/serve.ts
|
|
32
|
+
export default defineCommand({
|
|
33
|
+
description: "サーバーを起動する",
|
|
34
|
+
args: {
|
|
35
|
+
port: {
|
|
36
|
+
type: z.coerce.number().min(1).max(65535),
|
|
37
|
+
description: "ポート番号",
|
|
38
|
+
alias: "p",
|
|
39
|
+
default: 3000,
|
|
40
|
+
},
|
|
41
|
+
host: {
|
|
42
|
+
type: z.string(),
|
|
43
|
+
description: "ホスト名",
|
|
44
|
+
default: "localhost",
|
|
45
|
+
},
|
|
46
|
+
},
|
|
47
|
+
run({ args }) {
|
|
48
|
+
// args.port: number, args.host: string — 型推論される
|
|
49
|
+
console.log(`${args.host}:${args.port}`);
|
|
50
|
+
},
|
|
51
|
+
});
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
この1つの定義だけで、CLI フラグ・環境変数・設定ファイル・デフォルト値のすべてが統合される。
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
CLI flag my-app serve --port 8080 ← 最優先
|
|
58
|
+
env MYAPP_SERVE_PORT=5000 ← prefix + コマンドパス + arg 名で自動導出
|
|
59
|
+
config file { "serve": { "port": 4000 } } ← コマンドツリーと同じ構造
|
|
60
|
+
default 3000
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
どのソースから来た値も、最終的に同じ Zod スキーマでバリデーションされる。
|
|
64
|
+
|
|
65
|
+
### 環境変数の自動マッピング
|
|
66
|
+
|
|
67
|
+
`autoEnv` を指定すると、コマンドパス + arg 名から環境変数名を自動導出する。
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
const cli = createCLI({
|
|
71
|
+
name: "my-app",
|
|
72
|
+
autoEnv: { prefix: "MYAPP" },
|
|
73
|
+
});
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
| コマンド | arg | 自動導出される env 名 |
|
|
77
|
+
| ------------- | ------- | ------------------------- |
|
|
78
|
+
| `serve` | `port` | `MYAPP_SERVE_PORT` |
|
|
79
|
+
| `remote push` | `force` | `MYAPP_REMOTE_PUSH_FORCE` |
|
|
80
|
+
|
|
81
|
+
### 設定ファイルの自動マッピング
|
|
82
|
+
|
|
83
|
+
config ファイルの JSON 構造はコマンドツリーと一致する。
|
|
84
|
+
|
|
85
|
+
```json
|
|
86
|
+
{
|
|
87
|
+
"serve": { "port": 5000, "host": "0.0.0.0" },
|
|
88
|
+
"remote": { "push": { "force": true } }
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
my-app --config app.json serve
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### ヘルプ自動生成
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
$ my-app serve --help
|
|
100
|
+
|
|
101
|
+
サーバーを起動する
|
|
102
|
+
|
|
103
|
+
Usage: my-app serve [options]
|
|
104
|
+
|
|
105
|
+
Options:
|
|
106
|
+
-p, --port <port> ポート番号 (env: MYAPP_SERVE_PORT, default: 3000)
|
|
107
|
+
--host <host> ホスト名 (env: MYAPP_SERVE_HOST, default: localhost)
|
|
108
|
+
-h, --help ヘルプを表示する
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## ドキュメント
|
|
112
|
+
|
|
113
|
+
- [ファイルベースルーティング](docs/routing.md) — コマンドツリー、動的セグメント、params と args の分離
|
|
114
|
+
- [スキーマと値の解決](docs/schema.md) — defineCommand、args 定義、値の優先順位、ヘルプ生成
|
|
115
|
+
- [設定ファイルと環境変数](docs/config.md) — autoEnv、config ファイル階層、`--config` フラグ
|
|
116
|
+
- [内部アーキテクチャ](docs/architecture.md) — パイプライン設計、各モジュールの責務、処理トレース
|
|
117
|
+
- [既存ツールとの比較](docs/comparison.md) — commander / oclif / Pastel / Gud CLI / convict との比較
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@miyaoka/fsss",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "A CLI framework where your file structure becomes your command structure, and a single schema gives you typed values whether they come from flags, env vars, or config files.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"author": "miyaoka",
|
|
@@ -30,7 +30,9 @@
|
|
|
30
30
|
"dist"
|
|
31
31
|
],
|
|
32
32
|
"scripts": {
|
|
33
|
-
"
|
|
33
|
+
"prepack": "cp ../../README.md .",
|
|
34
|
+
"postpack": "rm README.md",
|
|
35
|
+
"prepare": "vite build",
|
|
34
36
|
"build": "vite build",
|
|
35
37
|
"dev": "vite build --watch",
|
|
36
38
|
"test": "bun test",
|