@hyperfrontend/features 0.1.0 → 0.2.0

package/cli/index.d.ts

@@ -1,5 +1,5 @@
 import { ResolvedFeatureConfig, FeatureContract, SecurityProtocol } from '..';
-import { resolveDevConfig, startDevServer } from '../server';
+import { resolveDevConfig, startDevServer, DevServerHandle } from '../server';
 import { createTree, commitChanges } from '../_dependencies/@hyperfrontend/project-scope/vfs/index.js';
 
 /**
@@ -30,6 +30,8 @@ interface CliFlags {
     readonly cwd?: string;
     /** Target entry file `init` wires the glue import into (`--entry`). */
     readonly entry?: string;
+    /** Acknowledge an explicit `--protocol none` build and produce an open connector (`--allow-open`). */
+    readonly allowOpen?: boolean;
     /** Suppress prompts and fail on any unresolved required key (`--ci`). */
     readonly ci: boolean;
     /** Suppress prompts, accepting defaults (`--yes`). */
@@ -104,6 +106,8 @@ interface ResolvedBuildBundle {
     readonly contract: FeatureContract;
     /** The resolved security envelope (`none` unless overridden). */
     readonly protocol: SecurityProtocol;
+    /** Whether the protocol came from a flag or the config file rather than the default. */
+    readonly protocolExplicit: boolean;
     /** Absolute path of the config file that was loaded, when one was found. */
     readonly sourcePath?: string;
 }
@@ -113,7 +117,7 @@ interface ResolvedBuildBundle {
  * replaces its whole top-level key (no deep merge).
  *
  * @param options - The working directory and parsed flags.
- * @returns The resolved config, loaded contract, protocol, and source path.
+ * @returns The resolved config, loaded contract, protocol (with its explicitness), and source path.
  * @throws {Error} When the config or contract is missing required keys or malformed.
  *
  * @example Resolving from a discovered config plus a flag override
@@ -125,9 +129,9 @@ declare function resolveBuildConfig(options: ResolveBuildConfigOptions): Promise
 
 /** Inputs handed to the builder for a single connector build. */
 interface BuildRunnerInput {
-    /** Temp directory holding the generated connector sources. */
+    /** Staging directory (inside the consumer project) holding the generated connector sources. */
     readonly projectRoot: string;
-    /** Workspace root the builder resolves against. */
+    /** The consumer project root, supplying `node_modules` and the TypeScript toolchain. */
     readonly workspaceRoot: string;
     /** Directory the bundled package is emitted into. */
     readonly outputPath: string;
@@ -153,9 +157,12 @@ interface RunBuildOptions extends BuildDeps {
     readonly stderr: NodeJS.WritableStream;
 }
 /**
- * Builds the connector: resolve config → generate the host connector into a temp
- * dir → bundle via the builder → pack a tarball into `--out`. A `v1`/`v2` security
- * protocol is required for production output, and the temp dir is always removed.
+ * Builds the connector: resolve config → generate the host connector into a
+ * hidden staging dir inside the project → bundle via the builder → pack a
+ * tarball into `--out`. A `v1`/`v2` security protocol is required for production
+ * output; an explicit `--protocol none` builds only when paired with
+ * `--allow-open`, acknowledging the open channel. The staging dir is always
+ * removed.
  *
  * @param options - Flags, working directory, output sinks, and injectable deps.
  * @returns The process exit code.
@@ -173,6 +180,8 @@ interface DevDeps {
     readonly resolveConfig?: typeof resolveDevConfig;
     /** Starts the resolved dev server. */
     readonly startServer?: typeof startDevServer;
+    /** Holds the command open while the servers run; receives the running handle and resolves once serving should end. Defaults to waiting for `SIGINT`/`SIGTERM`, then closing every server. */
+    readonly waitForClose?: (handle: DevServerHandle) => Promise<void>;
 }
 /** Inputs for a single `dev` invocation. */
 interface RunDevOptions extends DevDeps {
@@ -187,8 +196,10 @@ interface RunDevOptions extends DevDeps {
 }
 /**
  * Resolves the `hf-dev.config.*` through the shared tiered loader and starts the
- * dev server: one static server per app plus the debug UI. The returned promise
- * resolves once the servers are listening; the process stays alive serving them.
+ * dev server: one static server per app plus the debug UI. After printing the
+ * server URLs the returned promise stays pending while the servers run; it
+ * resolves with the success code once a shutdown signal (`SIGINT`/`SIGTERM`,
+ * e.g. Ctrl-C) arrives and every server has closed cleanly.
  *
  * @param options - Flags, working directory, output sinks, and injectable deps.
  * @returns The process exit code.
@@ -302,7 +313,7 @@ declare const EXIT_CANCELLED = 130;
  * Documents the three commands and the shared flag surface so the headless
  * (`--ci`) path is discoverable without reading the docs.
  */
-declare const USAGE = "@hyperfrontend/features \u2014 build, embed, and orchestrate micro-frontend features\n\nUsage: hf <command> [options]\n\nCommands:\n  init     Scaffold the feature glue module and wire it into your app\n  build    Generate the host connector, bundle it, and pack a tarball\n  dev      Resolve the dev-server config and start the debug UI\n\nOptions:\n  --name <name>         Feature name\n  --version <version>   Feature version\n  --contract <path>     Path to the *.contract.{json,ts,js} file\n  --entry <path>        Entry file to wire the glue import into (init)\n  --url <url>           URL the connector loads the feature from (build)\n  --protocol <none|v1|v2>  Security envelope enforced at build time\n  --out <dir>           Output directory for the built connector (build)\n  --apps <path>         Path to the dev-server apps array (dev)\n  --port <number>       Port the dev-server debug UI listens on (dev)\n  --config <path>       Path to the whole feature.config.* / hf-dev.config.* file\n  --cwd <dir>           Working-directory override\n  --ci, --yes           Run headlessly; error on any unresolved required key\n  --dry-run             Preview file changes without writing them\n  -h, --help            Print this help\n";
+declare const USAGE = "@hyperfrontend/features \u2014 build, embed, and orchestrate micro-frontend features\n\nUsage: hf <command> [options]\n\nCommands:\n  init     Scaffold the feature glue module and wire it into your app\n  build    Generate the host connector, bundle it, and pack a tarball\n  dev      Start the app servers and debug UI, serving until Ctrl-C\n\nOptions:\n  --name <name>         Feature name\n  --version <version>   Feature version\n  --contract <path>     Path to the *.contract.{json,ts,js} file\n  --entry <path>        Entry file to wire the glue import into (init)\n  --url <url>           URL the connector loads the feature from (build)\n  --protocol <none|v1|v2>  Security envelope enforced at build time\n  --allow-open          Acknowledge an explicit '--protocol none' and build an open, unauthenticated connector (build)\n  --out <dir>           Output directory for the built connector (build)\n  --apps <path>         Path to the dev-server apps array (dev)\n  --port <number>       Port the dev-server debug UI listens on (dev)\n  --config <path>       Path to the whole feature.config.* / hf-dev.config.* file\n  --cwd <dir>           Working-directory override\n  --ci, --yes           Run headlessly; error on any unresolved required key\n  --dry-run             Preview file changes without writing them\n  -h, --help            Print this help\n";
 
 export { DEV_CONFIG_BASENAME, EXIT_CANCELLED, EXIT_ERROR, EXIT_OK, FEATURE_CONFIG_BASENAME, USAGE, discoverConfigFile, loadModuleFile, parseCliArgs, resolveBuildConfig, runBuild, runDev, runFeaturesCli, runInit };
 export type { BuildDeps, BuildRunnerInput, CliFlags, DevDeps, InitDeps, ParsedArgs, ResolveBuildConfigOptions, ResolvedBuildBundle, RunBuildOptions, RunDevOptions, RunFeaturesCliOptions, RunInitOptions };