@ttsc/banner 0.30.3 → 0.31.0

package/lib/createTtscBanner.d.ts

@@ -0,0 +1,100 @@
+import type { ITtscBannerPluginConfig } from "./structures";
+/**
+ * The shape returned by a ttsc plugin factory function.
+ *
+ * Mirrors the ttsc plugin descriptor contract. The `source` field points to the
+ * Go source directory that the host will compile and cache as either an
+ * executable sidecar or linked native source.
+ */
+type TtscPluginDescriptor = {
+    /** The bundled driver host records actual writes and their physical sources. */
+    capabilities: {
+        emitProvenance: true;
+    };
+    /** Universal config-discovery inputs consumed by the native transform. */
+    hostInputs?: string[];
+    /** Evaluation-time fingerprints paired with {@link hostInputs}. */
+    hostInputHashes?: Record<string, string | null>;
+    /** Evaluation-time physical targets paired with {@link hostInputs}. */
+    hostInputRealpaths?: Record<string, string | null>;
+    /** Human-readable plugin name used in logs and error messages. */
+    name: string;
+    /** Absolute path to the Go source directory for this plugin. */
+    source: string;
+    /**
+     * Pipeline stage. `"transform"` plugins may rewrite source files; `"check"`
+     * plugins only produce diagnostics. The framework default is `"transform"`.
+     */
+    stage?: "check" | "transform";
+};
+/**
+ * Context object passed by the ttsc host to every plugin factory function.
+ *
+ * Module anchors locate shipped Go source. Project anchors locate user
+ * configuration, including when the host uses a generated wrapper tsconfig.
+ */
+type TtscPluginFactoryContext<TConfig> = {
+    /** Absolute path to the selected ttsc native helper, not a plugin binary. */
+    binary: string;
+    /** Working directory of the ttsc invocation. */
+    cwd: string;
+    /**
+     * Absolute path to the directory holding this descriptor module, the
+     * load-mode-independent replacement for `__dirname`.
+     */
+    dirname: string;
+    /**
+     * Absolute path to this descriptor module, the load-mode-independent
+     * replacement for `__filename`.
+     */
+    filename: string;
+    /** Host-declared anchor for implicit plugin config discovery. */
+    pluginConfigDir?: string;
+    /** The raw plugin entry from `compilerOptions.plugins[]`. */
+    plugin: TConfig;
+    /** Absolute path to the project root (directory containing tsconfig). */
+    projectRoot: string;
+    /** Absolute path to the resolved tsconfig. */
+    tsconfig: string;
+};
+/**
+ * Plugin factory called by the ttsc host to obtain the `@ttsc/banner`
+ * descriptor.
+ *
+ * The only banner-specific key accepted in the tsconfig plugin entry is
+ * `configFile`. Any other key that is not a known framework key is rejected
+ * with a specific error so users discover the correct configuration surface
+ * (the dedicated config file) rather than silently receiving no banner.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The default-export factory maps host module anchors to the shipped driver
+ *   and project anchors to config candidates. Discovery records all seven
+ *   candidate names in every directory from the anchor through the first one
+ *   holding a non-directory match, including absent paths and directory markers,
+ *   so creating a nearer config or a second file beside the match changes the
+ *   descriptor inputs. Native evaluation validates ambiguous or invalid config;
+ *   this factory supplies observations rather than treating existence as a
+ *   valid banner. SHA-256 covers candidate bytes and a distinct directory marker.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Registration validation, discovery observations and descriptor construction
+ *   have separate responsibilities. Private helpers isolate path discovery and
+ *   filesystem observations; they do not implement another config evaluator.
+ *   The driver path follows the installed package layout, while config anchors
+ *   follow the project because those two directories have different owners.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Framework keys, candidate filenames, package identity and stage encode the
+ *   supported registration contract. The descriptor neither evaluates user
+ *   JavaScript nor changes a foreign loader; it records a failed probe (an absent
+ *   or unreadable candidate) as a null hash or physical target, and native
+ *   evaluation reports the actual error.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc separates registration from config evaluation and explains why
+ *   unknown inline keys are rejected. Context and descriptor fields document
+ *   host anchoring and observed inputs. Paragraphs and reasons follow the
+ *   documentation skill; the exported factory is documented as a host entry.
+ */
+export default function createTtscBanner(context: TtscPluginFactoryContext<ITtscBannerPluginConfig>): TtscPluginDescriptor;
+export {};

package/lib/createTtscBanner.js

@@ -0,0 +1,167 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = createTtscBanner;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Keys that the ttsc plugin host injects into every plugin entry and are not
+ * owned by `@ttsc/banner`. The host validates registration; this factory
+ * rejects unknown banner options without rejecting those registration keys.
+ */
+const FRAMEWORK_KEYS = new Set([
+    "enabled",
+    "name",
+    "stage",
+    "transform",
+]);
+/**
+ * Plugin factory called by the ttsc host to obtain the `@ttsc/banner`
+ * descriptor.
+ *
+ * The only banner-specific key accepted in the tsconfig plugin entry is
+ * `configFile`. Any other key that is not a known framework key is rejected
+ * with a specific error so users discover the correct configuration surface
+ * (the dedicated config file) rather than silently receiving no banner.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The default-export factory maps host module anchors to the shipped driver
+ *   and project anchors to config candidates. Discovery records all seven
+ *   candidate names in every directory from the anchor through the first one
+ *   holding a non-directory match, including absent paths and directory markers,
+ *   so creating a nearer config or a second file beside the match changes the
+ *   descriptor inputs. Native evaluation validates ambiguous or invalid config;
+ *   this factory supplies observations rather than treating existence as a
+ *   valid banner. SHA-256 covers candidate bytes and a distinct directory marker.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Registration validation, discovery observations and descriptor construction
+ *   have separate responsibilities. Private helpers isolate path discovery and
+ *   filesystem observations; they do not implement another config evaluator.
+ *   The driver path follows the installed package layout, while config anchors
+ *   follow the project because those two directories have different owners.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Framework keys, candidate filenames, package identity and stage encode the
+ *   supported registration contract. The descriptor neither evaluates user
+ *   JavaScript nor changes a foreign loader; it records a failed probe (an absent
+ *   or unreadable candidate) as a null hash or physical target, and native
+ *   evaluation reports the actual error.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc separates registration from config evaluation and explains why
+ *   unknown inline keys are rejected. Context and descriptor fields document
+ *   host anchoring and observed inputs. Paragraphs and reasons follow the
+ *   documentation skill; the exported factory is documented as a host entry.
+ */
+function createTtscBanner(context) {
+    const entry = context.plugin;
+    for (const key of Object.keys(entry)) {
+        if (!FRAMEWORK_KEYS.has(key) && key !== "configFile") {
+            throw new Error(`@ttsc/banner: tsconfig plugin entry contains unsupported key ${JSON.stringify(key)}. ` +
+                `Banner options must be placed in a banner.config.{ts,cts,mts,js,cjs,mjs,json} file. ` +
+                `The only accepted key in the tsconfig entry is "configFile" (optional path to the config file).`);
+        }
+    }
+    const configInputs = bannerConfigInputs(context);
+    return {
+        capabilities: { emitProvenance: true },
+        hostInputHashes: configInputs.hashes,
+        hostInputRealpaths: configInputs.realpaths,
+        hostInputs: configInputs.inputs,
+        name: "@ttsc/banner",
+        // Point at the `driver/` directory one level above `lib/` in the
+        // installed package tree (where the Go sources live). `context.dirname`
+        // is this descriptor's own directory in every load mode, unlike the
+        // CommonJS `__dirname`, which is undefined under a `.ts`-source or ESM load.
+        source: node_path_1.default.resolve(context.dirname, "..", "driver"),
+        stage: "transform",
+    };
+}
+const BANNER_CONFIG_FILENAMES = [
+    "banner.config.json",
+    "banner.config.js",
+    "banner.config.cjs",
+    "banner.config.mjs",
+    "banner.config.ts",
+    "banner.config.cts",
+    "banner.config.mts",
+];
+/**
+ * Mirror native config resolution for a nonblank string `configFile` or for
+ * upward discovery, retaining the absent candidates that could supersede or
+ * make ambiguous the match. Native evaluation rejects any other `configFile`.
+ */
+function bannerConfigInputs(context) {
+    const configFile = context.plugin.configFile;
+    const base = node_path_1.default.resolve(context.pluginConfigDir ?? node_path_1.default.dirname(context.tsconfig));
+    if (typeof configFile === "string" && configFile.trim() !== "") {
+        const file = node_path_1.default.isAbsolute(configFile)
+            ? node_path_1.default.resolve(configFile)
+            : node_path_1.default.resolve(base, configFile);
+        return {
+            hashes: { [file]: hostInputHash(file) },
+            inputs: [file],
+            realpaths: { [file]: hostInputRealpath(file) },
+        };
+    }
+    return configDiscoveryInputs(base, BANNER_CONFIG_FILENAMES);
+}
+function configDiscoveryInputs(base, names) {
+    const inputs = [];
+    const hashes = {};
+    const realpaths = {};
+    for (let directory = base;; directory = node_path_1.default.dirname(directory)) {
+        const candidates = names.map((name) => node_path_1.default.join(directory, name));
+        inputs.push(...candidates);
+        for (const candidate of candidates) {
+            hashes[candidate] = hostInputHash(candidate);
+            realpaths[candidate] = hostInputRealpath(candidate);
+        }
+        if (candidates.some(configCandidateExists))
+            break;
+        const parent = node_path_1.default.dirname(directory);
+        if (parent === directory)
+            break;
+    }
+    return { hashes, inputs, realpaths };
+}
+function hostInputRealpath(file) {
+    try {
+        return node_fs_1.default.realpathSync.native(file);
+    }
+    catch {
+        return null;
+    }
+}
+/** Hash the exact candidate state observed before discovery selects a file. */
+function hostInputHash(file) {
+    try {
+        if (node_fs_1.default.statSync(file).isDirectory()) {
+            return node_crypto_1.default
+                .createHash("sha256")
+                .update("ttsc:host-input:directory\0")
+                .digest("hex");
+        }
+        return node_crypto_1.default
+            .createHash("sha256")
+            .update(node_fs_1.default.readFileSync(file))
+            .digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+/** Match the native discovery rule: a directory is never a config file. */
+function configCandidateExists(file) {
+    try {
+        return !node_fs_1.default.statSync(file).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=createTtscBanner.js.map

package/lib/createTtscBanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTtscBanner.js","sourceRoot":"","sources":["../src/createTtscBanner.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -1 +1,2 @@
 export * from "./structures/index";
+export { default } from "./createTtscBanner";

package/lib/index.js

@@ -17,133 +17,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = createTtscBanner;
-const node_crypto_1 = __importDefault(require("node:crypto"));
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
+exports.default = void 0;
 __exportStar(require("./structures/index"), exports);
-/**
- * Keys that the ttsc plugin host injects into every plugin entry and are not
- * owned by `@ttsc/banner`. These pass through the factory without validation so
- * the host can freely add new framework keys in the future.
- */
-const FRAMEWORK_KEYS = new Set([
-    "enabled",
-    "name",
-    "stage",
-    "transform",
-]);
-/**
- * Plugin factory for `@ttsc/banner` — called by the ttsc host to obtain the
- * plugin descriptor.
- *
- * The only banner-specific key accepted in the tsconfig plugin entry is
- * `configFile`. Any other key that is not a known framework key is rejected
- * with a specific error so users discover the correct configuration surface
- * (the dedicated config file) rather than silently receiving no banner.
- *
- * @internal
- */
-function createTtscBanner(context) {
-    const entry = context.plugin;
-    for (const key of Object.keys(entry)) {
-        if (!FRAMEWORK_KEYS.has(key) && key !== "configFile") {
-            throw new Error(`@ttsc/banner: tsconfig plugin entry contains unsupported key ${JSON.stringify(key)}. ` +
-                `Banner options must be placed in a banner.config.{ts,cts,mts,js,cjs,mjs,json} file. ` +
-                `The only accepted key in the tsconfig entry is "configFile" (optional path to the config file).`);
-        }
-    }
-    const configInputs = bannerConfigInputs(context);
-    return {
-        hostInputHashes: configInputs.hashes,
-        hostInputRealpaths: configInputs.realpaths,
-        hostInputs: configInputs.inputs,
-        name: "@ttsc/banner",
-        // Point at the `driver/` directory one level above `lib/` in the
-        // installed package tree (where the Go sources live). `context.dirname`
-        // is this descriptor's own directory in every load mode, unlike the
-        // CommonJS `__dirname`, which is undefined under a `.ts`-source or ESM load.
-        source: node_path_1.default.resolve(context.dirname, "..", "driver"),
-        stage: "transform",
-    };
-}
-const BANNER_CONFIG_FILENAMES = [
-    "banner.config.json",
-    "banner.config.js",
-    "banner.config.cjs",
-    "banner.config.mjs",
-    "banner.config.ts",
-    "banner.config.cts",
-    "banner.config.mts",
-];
-/** Mirror native config resolution while retaining missing priority probes. */
-function bannerConfigInputs(context) {
-    const configFile = context.plugin.configFile;
-    const base = node_path_1.default.resolve(context.pluginConfigDir ?? node_path_1.default.dirname(context.tsconfig));
-    if (typeof configFile === "string" && configFile.trim() !== "") {
-        const file = node_path_1.default.isAbsolute(configFile)
-            ? node_path_1.default.resolve(configFile)
-            : node_path_1.default.resolve(base, configFile);
-        return {
-            hashes: { [file]: hostInputHash(file) },
-            inputs: [file],
-            realpaths: { [file]: hostInputRealpath(file) },
-        };
-    }
-    return configDiscoveryInputs(base, BANNER_CONFIG_FILENAMES);
-}
-function configDiscoveryInputs(base, names) {
-    const inputs = [];
-    const hashes = {};
-    const realpaths = {};
-    for (let directory = base;; directory = node_path_1.default.dirname(directory)) {
-        const candidates = names.map((name) => node_path_1.default.join(directory, name));
-        inputs.push(...candidates);
-        for (const candidate of candidates) {
-            hashes[candidate] = hostInputHash(candidate);
-            realpaths[candidate] = hostInputRealpath(candidate);
-        }
-        if (candidates.some(configCandidateExists))
-            break;
-        const parent = node_path_1.default.dirname(directory);
-        if (parent === directory)
-            break;
-    }
-    return { hashes, inputs, realpaths };
-}
-function hostInputRealpath(file) {
-    try {
-        return node_fs_1.default.realpathSync.native(file);
-    }
-    catch {
-        return null;
-    }
-}
-/** Hash the exact candidate state observed before discovery selects a file. */
-function hostInputHash(file) {
-    try {
-        if (node_fs_1.default.statSync(file).isDirectory()) {
-            return node_crypto_1.default
-                .createHash("sha256")
-                .update("ttsc:host-input:directory\0")
-                .digest("hex");
-        }
-        return node_crypto_1.default
-            .createHash("sha256")
-            .update(node_fs_1.default.readFileSync(file))
-            .digest("hex");
-    }
-    catch {
-        return null;
-    }
-}
-/** Match the native discovery rule: a directory is never a config file. */
-function configCandidateExists(file) {
-    try {
-        return !node_fs_1.default.statSync(file).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
+var createTtscBanner_1 = require("./createTtscBanner");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(createTtscBanner_1).default; } });
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA,qDAAmC;AAEnC,uDAA6C;AAApC,4HAAA,OAAO,OAAA"}

package/lib/structures/ITtscBannerConfig.d.ts

@@ -1,5 +1,43 @@
-/** Standalone `banner.config.*` file shape consumed by `@ttsc/banner`. */
+/**
+ * Object exported by a standalone `banner.config.*` file.
+ *
+ * The native loader requires a nonblank text string. Keeping banner contents in
+ * this object gives JSON, JavaScript and TypeScript configuration the same
+ * value contract; the tsconfig plugin entry selects the file instead.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   A required string member expresses the loader's object payload. TypeScript
+ *   cannot express nonblank contents through this string type, so the native
+ *   loader validates that condition before formatting. The formatter preserves
+ *   content lines while normalizing CRLF and escaping closing delimiters; it
+ *   changes comment representation without treating text as executable source.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Banner content has one field in a dedicated config value. Registration and
+ *   config discovery stay in ITtscBannerPluginConfig because they select the
+ *   content's source rather than change its representation.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The text is consumer content, not a fixture-selected banner or a hardcoded
+ *   expected output. Required separators and the annotation are formatting
+ *   constants in the driver rather than hidden options in this value.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Interface and field JSDoc explain standalone config ownership, required
+ *   nonblank text, CRLF and trailing-line handling, terminator escaping and
+ *   removeComments behavior. Purpose, validation and formatting rationale are
+ *   separated into native paragraphs under the documentation skill; the type
+ *   acknowledgment covers its field without duplicating a checklist on that
+ *   property.
+ */
 export interface ITtscBannerConfig {
-    /** Text inserted into the generated `@packageDocumentation` block. */
+    /**
+     * Text placed before the generated `@packageDocumentation` annotation.
+     *
+     * Empty or whitespace-only values are rejected. The formatter preserves the
+     * supplied lines, removes trailing blank lines, normalizes CRLF and escapes
+     * comment terminators so the value cannot close the generated JSDoc block.
+     * The resulting comment follows the compiler's `removeComments` policy.
+     */
     text: string;
 }

package/lib/structures/ITtscBannerPluginConfig.d.ts

@@ -1,14 +1,64 @@
-/** `compilerOptions.plugins[]` entry shape consumed by `@ttsc/banner`. */
+/**
+ * Host registration and config-file selection for `@ttsc/banner`.
+ *
+ * This entry belongs in `compilerOptions.plugins[]`. Banner text belongs in the
+ * separate `ITtscBannerConfig` value so discovery and config evaluation have
+ * one supported home instead of an additional inline option surface.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Optional enabled distinguishes omission from an explicit false host switch;
+ *   transform carries the module specifier and configFile carries a separate
+ *   filesystem path. Those values belong to different resolution contracts, so
+ *   a binary path or inline text is not represented as banner configuration.
+ *   String typing does not establish path existence or nonblankness; the loader
+ *   validates an explicitly supplied configFile before evaluation.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The type separates two host registration fields from one banner-owned file
+ *   selector. Text belongs to the loaded ITtscBannerConfig object, leaving one
+ *   evaluation path instead of parallel inline and file configuration policies.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Host switches and configFile represent the supported registration
+ *   contract. Banner text has one typed config-file home, preventing a second
+ *   inline option shape from bypassing that loader's validation.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Interface and member JSDoc distinguish host registration from banner
+ *   text, disabled and omitted enabled states, module specifiers from config
+ *   or binary paths, and configFile anchoring, discovery, validation and
+ *   failure behavior. Separate paragraphs explain why generated wrapper
+ *   directories cannot become the discovery base, applying the documentation
+ *   skill's clear prose and rationale guidance to the complete type contract.
+ */
 export interface ITtscBannerPluginConfig {
-    /** Set to `false` to keep the entry while disabling this plugin. */
+    /**
+     * Set to `false` to retain the entry without running the plugin.
+     *
+     * Omission leaves the entry enabled. The ttsc host owns this switch; it is
+     * not a banner option passed through the standalone config file.
+     */
     enabled?: boolean;
-    /** Plugin module specifier. */
+    /**
+     * Module specifier the host resolves to the plugin factory.
+     *
+     * Use `@ttsc/banner` to register this package through the transform key. This
+     * names the factory module, not the banner config file or Go binary.
+     */
     transform?: string;
     /**
-     * Path to a `banner.config.*` file, resolved from the directory that contains
-     * the tsconfig. When omitted, `@ttsc/banner` walks up from that directory and
-     * uses the first `banner.config.{ts,cts,mts,js,cjs,mjs,json}` file it finds.
-     * Any other key in this entry is rejected with an error.
+     * Explicit banner config path, absolute or relative to the host's plugin
+     * config directory. Without that explicit anchor, resolution uses the
+     * tsconfig directory, or the invocation directory when no tsconfig is set.
+     *
+     * Omission searches upward from the same anchor for `banner.config.*`.
+     * Missing or ambiguous discovery is an error. An explicit value must be a
+     * nonblank string naming a supported config file. Banner-specific inline
+     * options such as text are rejected; host-owned registration keys remain
+     * permitted.
+     *
+     * The host anchor matters when the tsconfig is a generated wrapper: its
+     * temporary directory must not become the user's config-resolution base.
      */
     configFile?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/banner",
-  "version": "0.30.3",
+  "version": "0.31.0",
   "description": "First-party ttsc plugin that adds package-documentation JSDoc banners during emit.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -32,10 +32,11 @@
     "plugin/main.go"
   ],
   "devDependencies": {
+    "@wrtnlabs/evidence": "^0.3.1",
     "@types/node": "^25.3.0",
     "rimraf": "^6.1.2",
     "typescript": "^7.0.2",
-    "ttsc": "0.30.3"
+    "ttsc": "0.31.0"
   },
   "repository": {
     "type": "git",
@@ -48,6 +49,7 @@
   },
   "homepage": "https://ttsc.dev",
   "scripts": {
-    "build": "rimraf lib && tsc"
+    "build": "rimraf lib && tsc",
+    "evidence": "evidence"
   }
 }

package/plugin/main.go

@@ -2,7 +2,6 @@
 package main
 
 import (
-  "fmt"
   "os"
 
   "github.com/samchon/ttsc/packages/ttsc/utility"
@@ -10,27 +9,28 @@ import (
 
 const version = "0.0.1"
 
+// main exits the standalone process with its command dispatch status.
+//
+// These review grounds cover this private operation and its actual callees.
+// Go Evidence does not admit private declaration acknowledgment tags.
+//
+// Common: Principled implementation: os.Args excludes the executable name and os.Exit propagates the actual run status to the process consumer.
+// Common: Clear and simple design: The entrypoint binds process lifetime while run owns identity and stream delegation.
+// Common: Prohibited implementation shortcuts: The process uses the real command return status without rewriting failures or bypassing package registration.
+// Common: Meaningful documentation: The native comment names process status propagation separately from these native review grounds.
+// Portability: OS-neutral implementation: Go's os package supplies native argv and process exit semantics without host-specific command quoting.
 func main() {
   os.Exit(run(os.Args[1:]))
 }
 
+// run supplies this standalone plugin's identity and process streams to the
+// shared production utility dispatch; linked registration remains in init.
+//
+// Common: Principled implementation: The package identity and unchanged version constant reach the shared actual command owner with original argv and process writers.
+// Common: Clear and simple design: One delegation leaves command semantics with utility.RunCommandWithIO and package registration with the sibling init import.
+// Common: Prohibited implementation shortcuts: Production execution uses the same dispatch as direct units and retains the real host for build, transform and check.
+// Common: Meaningful documentation: Native prose identifies identity, process stream binding and unchanged linked registration separately from these native review grounds.
+// Portability: OS-neutral implementation: os supplies the native process streams and argv values without a shell or path reconstruction.
 func run(args []string) int {
-  if len(args) == 0 {
-    fmt.Fprintln(os.Stderr, "@ttsc/banner: command required (expected build|transform|check|version)")
-    return 2
-  }
-  switch args[0] {
-  case "-v", "--version", "version":
-    fmt.Fprintf(os.Stdout, "@ttsc/banner %s\n", version)
-    return 0
-  case "build":
-    return utility.RunBuild(args[1:])
-  case "transform":
-    return utility.RunTransform(args[1:])
-  case "check":
-    return utility.RunCheck(args[1:])
-  default:
-    fmt.Fprintf(os.Stderr, "@ttsc/banner: unknown command %q\n", args[0])
-    return 2
-  }
+  return utility.RunCommandWithIO("@ttsc/banner", version, args, os.Stdout, os.Stderr)
 }