@geektech/tsone-cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Geek Tech Team
+
+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/README.md

@@ -0,0 +1,175 @@
+# TSone CLI
+
+`@geektech/tsone-cli` is the Bun-native development and build CLI for TSone
+applications. It requires Bun `>=1.3.0`.
+
+## Installation
+
+Install the framework and its development tooling together:
+
+```bash
+bun add @geektech/tsone @geektech/tsone-cli
+```
+
+## Application Entry
+
+The default entry is `src/main.ts`. It must export a named `app` whose value
+provides `renderHtmlDocument()`; a TSone application created by `createApp`
+satisfies that contract:
+
+```typescript
+import { Component, VNode, createApp } from '@geektech/tsone';
+
+class App extends Component<object, object> {
+  protected initState(): object {
+    return {};
+  }
+
+  protected initStyles(): void {}
+
+  protected render(): VNode {
+    return { tag: 'main', children: ['Hello TSone'] };
+  }
+}
+
+export const app = createApp({
+  root: App,
+  document: { title: 'TSone App' },
+});
+
+app.mount();
+```
+
+The export must be written as `export const app`; a default export or another
+name is not used by the CLI.
+
+## Configuration
+
+Create an optional `tsone.config.ts` in the project root. The config file
+supports only a plain-object default export; functional or function-valued
+config is not supported. `defineConfig()` supplies type checking without
+changing the object.
+
+```typescript
+import { defineConfig } from '@geektech/tsone-cli';
+
+export default defineConfig({
+  server: {
+    proxy: {
+      '/api': {
+        target: 'http://localhost:3000',
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/api/, ''),
+      },
+    },
+  },
+  build: { outDir: 'dist' },
+});
+```
+
+A proxy can also use the string shorthand when no other options are needed:
+
+```typescript
+export default defineConfig({
+  server: {
+    proxy: {
+      '/backend': 'http://localhost:4000',
+    },
+  },
+});
+```
+
+Defaults:
+
+- `entry`: `src/main.ts`
+- `server.host`: `127.0.0.1`
+- `server.port`: `52211`
+- `server.proxy`: `{}`
+- `build.outDir`: `dist`
+
+`build.outDir` must resolve to a child directory inside the project root. The
+project root itself, an outside path, and a path that escapes through a symlink
+are rejected before the output directory is removed.
+
+## Command Line
+
+Development and build options are deliberately separate:
+
+```text
+tsone dev [--host <host>] [--port <port>]
+tsone build [--out-dir <path>]
+```
+
+`dev` accepts only `--host` and `--port`; `build` accepts only `--out-dir`.
+Options override `tsone.config.ts`. Both separated and equals forms work, for
+example `--port 3000`, `--port=3000`, `--out-dir output`, and
+`--out-dir=output`.
+
+`tsone dev` serves the generated HTML at `/` and `/index.html`. Each document
+build writes an immutable browser ESM generation beneath the internal
+`.tsone/dev/` directory and references exact `/dev/<session>/<generation>/...`
+JavaScript and stylesheet URLs. Bun uses that exact generation URL as its
+public path, so emitted file-asset strings are absolute URLs under the same
+generation and resolve correctly from the document URL across concurrent pages.
+`/bundle.js` remains a compatibility alias that rebuilds and redirects to the
+latest exact entry URL. Other unmatched paths return 404. The `.tsone/`
+directory is generated tooling output and can be removed while the development
+server is stopped. A `.tsone` path that resolves outside the project through a
+symlink is rejected before the development server starts.
+
+`tsone build` writes a Bun browser bundle and `index.html` to the safe output
+directory.
+
+## Development Proxy
+
+The development server serves HTTP only. Proxy targets may use HTTP or HTTPS.
+A rule is matched as a literal pathname prefix, and the longest matching prefix
+wins. The proxy preserves the query string, request method, request body, and
+end-to-end headers while removing hop-by-hop headers. `changeOrigin: true`
+changes the upstream `Host` header; otherwise the incoming host is retained.
+`rewrite` synchronously changes the pathname before it is joined to the target
+base path. An upstream connection failure returns the fixed response
+`502 Bad Gateway`.
+
+## Programmatic API
+
+All tooling APIs come from `@geektech/tsone-cli`, not from the framework root:
+
+```typescript
+import {
+  build,
+  defineConfig,
+  resolveConfig,
+  startDevServer,
+} from '@geektech/tsone-cli';
+
+const config = defineConfig({ build: { outDir: 'output' } });
+const resolved = await resolveConfig({ root: process.cwd(), config });
+const server = await startDevServer({ root: resolved.root, port: 0 });
+
+try {
+  console.log(server.url);
+} finally {
+  server.stop();
+}
+
+const result = await build({ root: resolved.root, outDir: 'release' });
+console.log(result.root, result.outDir, result.assetsBuilt);
+```
+
+- `defineConfig(config)` returns the same typed config object.
+- `resolveConfig(options?)` validates and merges defaults, a config file,
+  direct config, and host/port/outDir overrides. It returns absolute `root`,
+  `entry`, and `build.outDir` values plus the resolved server configuration.
+- `startDevServer(options?)` resolves the configuration and returns the Bun
+  server. The caller owns its lifecycle and must call `server.stop()`.
+- `build(options?)` validates the entry and output path, then returns
+  `{ root, outDir, assetsBuilt }`; the paths in the result are absolute.
+
+## Version 1 Scope
+
+The development server serves HTTP only. Proxy targets may use HTTP or HTTPS.
+CLI v1 has no config plugins, WebSocket, HMR, SSR, functional config, `public/`
+directory copying, or public `minify` and `sourcemap` configuration.
+Development bundles use an internal inline source map, while production build
+minification and source-map controls are intentionally not configurable.

package/bin/tsone.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env bun
+import { existsSync } from 'node:fs';
+
+const builtCli = new URL('../dist/cli.js', import.meta.url);
+const sourceCli = new URL('../src/cli.ts', import.meta.url);
+const cli = (await import(
+  existsSync(builtCli) ? builtCli.href : sourceCli.href
+)) as {
+  runCli: () => Promise<void>;
+};
+
+await cli.runCli();

package/dist/build-output.d.ts

@@ -0,0 +1,9 @@
+interface BuildOutputDescriptor {
+    path: string;
+    kind: string;
+}
+export declare function isEntryJavaScriptOutput(output: BuildOutputDescriptor): boolean;
+export declare function isStylesheetOutput(output: {
+    path: string;
+}): boolean;
+export {};

package/dist/build.d.ts

@@ -0,0 +1,2 @@
+import type { BuildOptions, BuildResult } from './types';
+export declare function build(options?: BuildOptions): Promise<BuildResult>;

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+export interface DevCliArgs {
+    command: 'dev';
+    host?: string;
+    port?: number;
+}
+export interface BuildCliArgs {
+    command: 'build';
+    outDir?: string;
+}
+export type CliArgs = DevCliArgs | BuildCliArgs;
+export declare function parseCliArgs(argv: string[]): CliArgs;
+export declare function runCli(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,109 @@
+// @bun
+import {
+  build,
+  startDevServer
+} from "./index-jmtdrrbw.js";
+
+// src/cli.ts
+var USAGE = [
+  "Usage:",
+  "  tsone dev [--host <host>] [--port <port>]",
+  "  tsone build [--out-dir <path>]"
+].join(`
+`);
+function parseCliArgs(argv) {
+  const command = argv[0];
+  if (command !== "dev" && command !== "build") {
+    throw parseError(command === undefined ? "Missing command" : `Unknown command: ${command}`);
+  }
+  const options = new Map;
+  for (let index = 1;index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) {
+      throw parseError(`Unexpected positional argument: ${token}`);
+    }
+    const { name, inlineValue } = splitOption(token);
+    assertKnownOption(name);
+    assertSupportedOption(command, name);
+    if (options.has(name)) {
+      throw parseError(`Duplicate option: ${name}`);
+    }
+    const value = inlineValue ?? argv[index + 1];
+    if (value === undefined || value === "" || value.startsWith("--")) {
+      throw parseError(`Missing value for option: ${name}`);
+    }
+    if (inlineValue === undefined) {
+      index += 1;
+    }
+    options.set(name, value);
+  }
+  if (command === "dev") {
+    const port = options.get("--port");
+    return {
+      command,
+      ...options.has("--host") ? { host: options.get("--host") } : {},
+      ...port === undefined ? {} : { port: parsePort(port) }
+    };
+  }
+  return {
+    command,
+    ...options.has("--out-dir") ? { outDir: options.get("--out-dir") } : {}
+  };
+}
+async function runCli(argv = process.argv.slice(2)) {
+  const args = parseCliArgs(argv);
+  if (args.command === "dev") {
+    const server = await startDevServer({
+      ...args.host === undefined ? {} : { host: args.host },
+      ...args.port === undefined ? {} : { port: args.port }
+    });
+    console.log(`TSone dev server listening at http://${server.hostname}:${server.port}`);
+    return;
+  }
+  const result = await build(args.outDir === undefined ? {} : { outDir: args.outDir });
+  console.log(`TSone build completed: ${result.outDir} (${result.assetsBuilt.length} assets)`);
+}
+function splitOption(token) {
+  const equalsIndex = token.indexOf("=");
+  if (equalsIndex === -1) {
+    return { name: token };
+  }
+  return {
+    name: token.slice(0, equalsIndex),
+    inlineValue: token.slice(equalsIndex + 1)
+  };
+}
+function assertKnownOption(name) {
+  if (name === "--host" || name === "--port" || name === "--out-dir") {
+    return;
+  }
+  throw parseError(`Unknown option: ${name}`);
+}
+function assertSupportedOption(command, name) {
+  const supported = command === "dev" && (name === "--host" || name === "--port") || command === "build" && name === "--out-dir";
+  if (!supported) {
+    throw parseError(`Option ${name} is not supported for ${command}`);
+  }
+}
+function parsePort(value) {
+  if (!/^\d+$/.test(value)) {
+    throw parseError("Port must be an integer between 0 and 65535");
+  }
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw parseError("Port must be an integer between 0 and 65535");
+  }
+  return port;
+}
+function parseError(message) {
+  return new Error(`${message}
+
+${USAGE}`);
+}
+export {
+  runCli,
+  parseCliArgs
+};
+
+//# debugId=AB0F04E26576496764756E2164756E21
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/cli.ts"],
+  "sourcesContent": [
+    "import { build } from './build';\nimport { startDevServer } from './server';\n\nconst USAGE = [\n  'Usage:',\n  '  tsone dev [--host <host>] [--port <port>]',\n  '  tsone build [--out-dir <path>]',\n].join('\\n');\n\nexport interface DevCliArgs {\n  command: 'dev';\n  host?: string;\n  port?: number;\n}\n\nexport interface BuildCliArgs {\n  command: 'build';\n  outDir?: string;\n}\n\nexport type CliArgs = DevCliArgs | BuildCliArgs;\n\nexport function parseCliArgs(argv: string[]): CliArgs {\n  const command = argv[0];\n  if (command !== 'dev' && command !== 'build') {\n    throw parseError(\n      command === undefined ? 'Missing command' : `Unknown command: ${command}`\n    );\n  }\n\n  const options = new Map<string, string>();\n  for (let index = 1; index < argv.length; index += 1) {\n    const token = argv[index];\n    if (!token.startsWith('--')) {\n      throw parseError(`Unexpected positional argument: ${token}`);\n    }\n\n    const { name, inlineValue } = splitOption(token);\n    assertKnownOption(name);\n    assertSupportedOption(command, name);\n    if (options.has(name)) {\n      throw parseError(`Duplicate option: ${name}`);\n    }\n\n    const value = inlineValue ?? argv[index + 1];\n    if (value === undefined || value === '' || value.startsWith('--')) {\n      throw parseError(`Missing value for option: ${name}`);\n    }\n    if (inlineValue === undefined) {\n      index += 1;\n    }\n    options.set(name, value);\n  }\n\n  if (command === 'dev') {\n    const port = options.get('--port');\n    return {\n      command,\n      ...(options.has('--host') ? { host: options.get('--host') } : {}),\n      ...(port === undefined ? {} : { port: parsePort(port) }),\n    };\n  }\n\n  return {\n    command,\n    ...(options.has('--out-dir') ? { outDir: options.get('--out-dir') } : {}),\n  };\n}\n\nexport async function runCli(\n  argv: string[] = process.argv.slice(2)\n): Promise<void> {\n  const args = parseCliArgs(argv);\n\n  if (args.command === 'dev') {\n    const server = await startDevServer({\n      ...(args.host === undefined ? {} : { host: args.host }),\n      ...(args.port === undefined ? {} : { port: args.port }),\n    });\n    console.log(\n      `TSone dev server listening at http://${server.hostname}:${server.port}`\n    );\n    return;\n  }\n\n  const result = await build(\n    args.outDir === undefined ? {} : { outDir: args.outDir }\n  );\n  console.log(\n    `TSone build completed: ${result.outDir} (${result.assetsBuilt.length} assets)`\n  );\n}\n\nfunction splitOption(token: string): { name: string; inlineValue?: string } {\n  const equalsIndex = token.indexOf('=');\n  if (equalsIndex === -1) {\n    return { name: token };\n  }\n\n  return {\n    name: token.slice(0, equalsIndex),\n    inlineValue: token.slice(equalsIndex + 1),\n  };\n}\n\nfunction assertKnownOption(name: string): void {\n  if (name === '--host' || name === '--port' || name === '--out-dir') {\n    return;\n  }\n\n  throw parseError(`Unknown option: ${name}`);\n}\n\nfunction assertSupportedOption(\n  command: CliArgs['command'],\n  name: string\n): void {\n  const supported =\n    (command === 'dev' && (name === '--host' || name === '--port')) ||\n    (command === 'build' && name === '--out-dir');\n\n  if (!supported) {\n    throw parseError(`Option ${name} is not supported for ${command}`);\n  }\n}\n\nfunction parsePort(value: string): number {\n  if (!/^\\d+$/.test(value)) {\n    throw parseError('Port must be an integer between 0 and 65535');\n  }\n\n  const port = Number(value);\n  if (!Number.isInteger(port) || port < 0 || port > 65535) {\n    throw parseError('Port must be an integer between 0 and 65535');\n  }\n\n  return port;\n}\n\nfunction parseError(message: string): Error {\n  return new Error(`${message}\\n\\n${USAGE}`);\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "AB0F04E26576496764756E2164756E21",
+  "names": []
+}

package/dist/config.d.ts

@@ -0,0 +1,3 @@
+import type { ResolveConfigOptions, ResolvedConfig, UserConfig } from './types';
+export declare function defineConfig(config: UserConfig): UserConfig;
+export declare function resolveConfig(options?: ResolveConfigOptions): Promise<ResolvedConfig>;