@miyaoka/fsss 0.2.1 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 miyaoka
+
+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/dist/cli.d.ts

@@ -5,6 +5,7 @@ interface CLIOptions {
     name: string;
     commandsDir?: string;
     autoEnv?: AutoEnvConfig;
+    defaultCommand?: string;
 }
 interface CLI {
     run: () => Promise<void>;

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAaA,UAAU,aAAa;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,UAAU,GAAG;IACX,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAgFD,iBAAS,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,GAAG,CA4G3C;AAED,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,YAAY,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAkBA,UAAU,aAAa;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,GAAG;IACX,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAgFD,iBAAS,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,GAAG,CAoJ3C;AAED,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,YAAY,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC"}

package/dist/help.d.ts

@@ -15,6 +15,16 @@ interface SubcommandHelpConfig {
 }
 declare function generateSubcommandHelp(config: SubcommandHelpConfig): string;
 declare function generateValidationErrorHelp(helpText: string, errors: string[]): string;
-export { generateHelp, generateSubcommandHelp, generateValidationErrorHelp };
-export type { HelpConfig, SubcommandHelpConfig };
+interface DefaultCommandHelpConfig {
+    programName: string;
+    defaultCommandName: string;
+    commandPath: string[];
+    description?: string;
+    argsDefs?: ArgsDefs;
+    envPrefix?: string;
+    availableEntries: AvailableEntry[];
+}
+declare function generateDefaultCommandHelp(config: DefaultCommandHelpConfig): string;
+export { generateDefaultCommandHelp, generateHelp, generateSubcommandHelp, generateValidationErrorHelp, };
+export type { DefaultCommandHelpConfig, HelpConfig, SubcommandHelpConfig };
 //# sourceMappingURL=help.d.ts.map

package/dist/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAU,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGhD,UAAU,UAAU;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAkED,iBAAS,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CA8DhD;AAGD,UAAU,oBAAoB;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gBAAgB,EAAE,cAAc,EAAE,CAAC;CACpC;AAED,iBAAS,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAuBpE;AAID,iBAAS,2BAA2B,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAG/E;AAED,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,oBAAoB,EAAE,CAAC"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAU,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGhD,UAAU,UAAU;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAkED,iBAAS,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CA8DhD;AAGD,UAAU,oBAAoB;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gBAAgB,EAAE,cAAc,EAAE,CAAC;CACpC;AAED,iBAAS,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAuBpE;AAID,iBAAS,2BAA2B,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAG/E;AAID,UAAU,wBAAwB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,cAAc,EAAE,CAAC;CACpC;AAED,iBAAS,0BAA0B,CAAC,MAAM,EAAE,wBAAwB,GAAG,MAAM,CAiE5E;AAED,OAAO,EACL,0BAA0B,EAC1B,YAAY,EACZ,sBAAsB,EACtB,2BAA2B,GAC5B,CAAC;AACF,YAAY,EAAE,wBAAwB,EAAE,UAAU,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/index.js

@@ -138,6 +138,35 @@ function generateValidationErrorHelp(e, t) {
 		e
 	].join("\n");
 }
+function generateDefaultCommandHelp(e) {
+	let { programName: t, defaultCommandName: n, commandPath: r, description: i, argsDefs: a, envPrefix: o, availableEntries: s } = e, c = [];
+	if (i !== void 0 && (c.push(i), c.push("")), a !== void 0 && Object.entries(a).some(([, e]) => e.positional !== !0) ? c.push(`Usage: ${t} [options]`) : c.push(`Usage: ${t}`), c.push(`       ${t} <command>`), c.push(""), a !== void 0) {
+		let e = Object.entries(a).filter(([, e]) => e.positional !== !0);
+		if (e.length > 0) {
+			c.push("Options:");
+			let t = e.map(([e, t]) => formatOptionLine(e, t, o, r));
+			t.push(formatHelpLine());
+			let n = Math.max(...t.map((e) => e.left.length));
+			for (let e of t) {
+				let t = " ".repeat(n - e.left.length + COLUMN_GAP);
+				c.push(`${INDENT}${e.left}${t}${e.right}`);
+			}
+			c.push("");
+		}
+	}
+	if (s.length > 0) {
+		c.push("Available commands:");
+		for (let e of s) {
+			if (e.isDynamic) {
+				c.push(`${INDENT}<${e.paramName}>`);
+				continue;
+			}
+			let t = e.name === n ? " (default)" : "";
+			c.push(`${INDENT}${e.name}${t}`);
+		}
+	}
+	return c.join("\n");
+}
 var LONG_FLAG_PREFIX = "--", SHORT_FLAG_PREFIX = "-", DOUBLE_DASH = "--", NEGATION_PREFIX = "--no-", BOOLEAN_TRUE = "true", BOOLEAN_FALSE = "false";
 function addFlag(e, t, n) {
 	let r = e.get(t);
@@ -426,62 +455,84 @@ function extractFrameworkFlags(e) {
 	};
 }
 function createCLI(e) {
-	let t = e.commandsDir ?? DEFAULT_COMMANDS_DIR, n = e.name, r = e.autoEnv?.prefix;
-	async function a() {
-		let { configPath: e, remainingTokens: a } = extractFrameworkFlags(process.argv.slice(ARGV_SKIP)), o = await resolveRoute(t, a);
-		if (o.kind === "unresolved") {
-			let e = generateSubcommandHelp({
-				programName: n,
-				commandPath: extractPartialCommandPath(t, o.stoppedDir),
-				availableEntries: o.availableEntries
-			});
-			console.log(e);
-			return;
+	let t = e.commandsDir ?? DEFAULT_COMMANDS_DIR, r = e.name, a = e.autoEnv?.prefix, o = e.defaultCommand;
+	async function s() {
+		let { configPath: e, remainingTokens: s } = extractFrameworkFlags(process.argv.slice(ARGV_SKIP)), c = await resolveRoute(t, s);
+		if (c.kind === "unresolved") {
+			let e = resolve(c.stoppedDir) === resolve(t), i = s.length > 0 && !s[0].startsWith("-");
+			if (e && o !== void 0 && !i) {
+				if (s.includes("--help") || s.includes("-h")) {
+					let e = await resolveRoute(t, [o]);
+					if (e.kind === "unresolved") throw Error(`defaultCommand "${o}" does not match any command file`);
+					let n = (await import(e.filePath)).default, i = n.args ?? {}, s = generateDefaultCommandHelp({
+						programName: r,
+						defaultCommandName: o,
+						commandPath: extractCommandPath(t, e.filePath),
+						description: n.description,
+						argsDefs: Object.keys(i).length > 0 ? i : void 0,
+						envPrefix: a,
+						availableEntries: c.availableEntries
+					});
+					console.log(s);
+					return;
+				}
+				let e = await resolveRoute(t, [o, ...s]);
+				if (e.kind === "unresolved") throw Error(`defaultCommand "${o}" does not match any command file`);
+				c = e;
+			} else {
+				let e = generateSubcommandHelp({
+					programName: r,
+					commandPath: extractPartialCommandPath(t, c.stoppedDir),
+					availableEntries: c.availableEntries
+				});
+				console.log(e);
+				return;
+			}
 		}
-		let s = (await import(o.filePath)).default, c = s.args ?? {}, l = extractCommandPath(t, o.filePath), u = generateHelp({
-			programName: n,
-			commandPath: l,
-			description: s.description,
-			argsDefs: Object.keys(c).length > 0 ? c : void 0,
-			envPrefix: r
+		let l = (await import(c.filePath)).default, u = l.args ?? {}, d = extractCommandPath(t, c.filePath), f = generateHelp({
+			programName: r,
+			commandPath: d,
+			description: l.description,
+			argsDefs: Object.keys(u).length > 0 ? u : void 0,
+			envPrefix: a
 		});
-		if (o.remainingTokens.includes("--help") || o.remainingTokens.includes("-h")) {
-			console.log(u);
+		if (c.remainingTokens.includes("--help") || c.remainingTokens.includes("-h")) {
+			console.log(f);
 			return;
 		}
-		let d = buildParserConfig(c), f;
+		let p = buildParserConfig(u), m;
 		try {
-			let t = parseTokens(o.remainingTokens, d), i = await loadMergedConfig(n, e);
-			f = validateArgs(c, resolveValues({
-				argsDefs: c,
+			let t = parseTokens(c.remainingTokens, p), n = await loadMergedConfig(r, e);
+			m = validateArgs(u, resolveValues({
+				argsDefs: u,
 				parsedTokens: t,
 				env: process.env,
-				config: i,
-				commandPath: l,
-				envPrefix: r
+				config: n,
+				commandPath: d,
+				envPrefix: a
 			}));
 		} catch (e) {
 			if (e instanceof ZodError) {
 				let t = e.issues.map((e) => `${e.path.join(".")}: ${e.message}`);
-				console.error(generateValidationErrorHelp(u, t)), process.exit(EXIT_CODE_ERROR);
+				console.error(generateValidationErrorHelp(f, t)), process.exit(EXIT_CODE_ERROR);
 			}
-			throw e instanceof Error && (console.error(generateValidationErrorHelp(u, [e.message])), process.exit(EXIT_CODE_ERROR)), e;
+			throw e instanceof Error && (console.error(generateValidationErrorHelp(f, [e.message])), process.exit(EXIT_CODE_ERROR)), e;
 		}
-		let { extensions: p, middlewares: m } = await scanPluginsAlongPath(o.traversedDirs, { cliName: n }), h = {
-			commandPath: l,
-			params: o.params,
-			args: f,
-			extensions: p
+		let { extensions: h, middlewares: g } = await scanPluginsAlongPath(c.traversedDirs, { cliName: r }), _ = {
+			commandPath: d,
+			params: c.params,
+			args: m,
+			extensions: h
 		};
-		await buildMiddlewareChain(m, async (e) => {
-			await s.run({
+		await buildMiddlewareChain(g, async (e) => {
+			await l.run({
 				params: e.params,
 				args: e.args,
 				extensions: e.extensions
 			});
-		})(h);
+		})(_);
 	}
-	return { run: a };
+	return { run: s };
 }
 function defineCommand(e) {
 	return e;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miyaoka/fsss",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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.",
   "type": "module",
   "author": "miyaoka",
@@ -32,28 +32,25 @@
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@tsconfig/node24": "24.0.4",
+    "@types/bun": "1.3.9",
+    "oxfmt": "0.31.0",
+    "oxlint": "1.46.0",
+    "oxlint-tsgolint": "0.12.0",
+    "typescript": "5.9.3",
+    "unplugin-dts": "1.0.0-beta.6",
+    "vite": "8.0.0-beta.13"
+  },
   "scripts": {
-    "prepack": "cp ../../README.md .",
-    "postpack": "rm README.md",
-    "prepare": "vite build",
     "build": "vite build",
     "dev": "vite build --watch",
     "test": "bun test",
     "typecheck": "tsgo --noEmit",
     "lint": "oxlint --type-aware .",
     "fix": "oxlint --type-aware --fix . && oxfmt ."
-  },
-  "dependencies": {
-    "zod": "catalog:"
-  },
-  "devDependencies": {
-    "@tsconfig/node24": "catalog:",
-    "@types/bun": "catalog:",
-    "oxfmt": "catalog:",
-    "oxlint": "catalog:",
-    "oxlint-tsgolint": "catalog:",
-    "typescript": "catalog:",
-    "unplugin-dts": "catalog:",
-    "vite": "catalog:"
   }
-}
+}