@junobuild/cli-tools 0.1.9 → 0.2.0-next-2025-05-23

package/dist/types/commands/build.d.ts

@@ -1,4 +1,27 @@
 import type { Message, Metafile } from 'esbuild';
+/**
+ * Builds an ECMAScript module (ESM) bundle for browser use using `esbuild`.
+ *
+ * This function:
+ * - Ensures `esbuild` is available.
+ * - Deletes the existing output file if it exists.
+ * - Builds the input file with optimizations: minification, tree-shaking, etc.
+ * - Returns the esbuild `metafile`, version, and any build errors or warnings.
+ *
+ * @param {Object} options - Build configuration.
+ * @param {string} options.infile - The path to the input file to be bundled.
+ * @param {string} options.outfile - The path where the output bundle should be written.
+ * @param {Object<string, string>} [options.banner] - Optional banner to prepend to the generated file.
+ *
+ * @returns {Promise<{
+ *   metafile: Metafile,
+ *   errors: Message[],
+ *   warnings: Message[],
+ *   version: string
+ * }>} An object containing the esbuild metafile, build errors/warnings, and the version of esbuild used.
+ *
+ * @throws Will exit the process if `esbuild` is not installed.
+ */
 export declare const buildEsm: ({ infile, outfile, banner }: {
     infile: string;
     outfile: string;

package/dist/types/commands/deploy.d.ts

@@ -1,18 +1,56 @@
 import type { CliConfig } from '@junobuild/config';
-import type { FileDetails, ListAssets, UploadFile } from '../types/deploy';
+import type { DeployResult, ListAssets, UploadFile } from '../types/deploy';
+/**
+ * Executes all configured pre-deploy hooks defined in the Juno configuration.
+ *
+ * This function is typically run before uploading or deploying any assets to
+ * perform validations, code generation, or other preparatory tasks.
+ *
+ * @param {Object} options - The function parameters.
+ * @param {CliConfig} options.config - The full configuration object containing hook definitions.
+ * @returns {Promise<void>} Resolves once all predeploy hooks have been executed.
+ */
 export declare const preDeploy: ({ config: { predeploy } }: {
     config: CliConfig;
 }) => Promise<void>;
+/**
+ * Executes all configured post-deploy hooks defined in the Juno configuration.
+ *
+ * This function is typically run after a successful deployment to perform cleanup,
+ * logging, or integration tasks (e.g., sending Slack notifications).
+ *
+ * @param {Object} options - The function parameters.
+ * @param {CliConfig} options.config - The full configuration object containing hook definitions.
+ * @returns {Promise<void>} Resolves once all postdeploy hooks have been executed.
+ */
 export declare const postDeploy: ({ config: { postdeploy } }: {
     config: CliConfig;
 }) => Promise<void>;
+/**
+ * Prepares and uploads dapp assets to a satellite.
+ *
+ * This function handles:
+ * 1. Resolving source files to upload.
+ * 2. Verifying that enough memory is available (via `assertMemory`).
+ * 3. Uploading all valid files using the provided `uploadFile` function.
+ *
+ * If no files are detected (e.g., all files are unchanged), the deploy is skipped.
+ *
+ * @param {Object} options - Deployment options.
+ * @param {CliConfig} options.config - The CLI configuration object.
+ * @param {ListAssets} options.listAssets - A function to list existing files on the target.
+ * @param {Function} [options.assertSourceDirExists] - Optional check to ensure source directory exists.
+ * @param {Function} options.assertMemory - A function to ensure enough memory is available.
+ * @param {UploadFile} options.uploadFile - A function responsible for uploading a single file.
+ *
+ * @returns {Promise<DeployResult>} An object containing the result of the deploy:
+ *   - `skipped` if no files were found.
+ *   - `deployed` and a list of uploaded files if the deploy succeeded.
+ */
 export declare const deploy: ({ assertMemory, uploadFile, ...rest }: {
     config: CliConfig;
     listAssets: ListAssets;
     assertSourceDirExists?: (source: string) => void;
     assertMemory: () => Promise<void>;
     uploadFile: UploadFile;
-}) => Promise<{
-    sourceFiles: FileDetails[];
-    sourceAbsolutePath: string;
-}>;
+}) => Promise<DeployResult>;

package/dist/types/commands/proposals.d.ts

@@ -0,0 +1,32 @@
+import { type CdnParameters, type ProposalType } from '@junobuild/cdn';
+import type { DeployResult } from '../types/deploy';
+/**
+ * Deploys changes using a proposal-based workflow, optionally try auto-committing the proposal.
+ *
+ * This function:
+ * 1. Initializes a new change (proposal) in the CDN.
+ * 2. Executes the provided `deploy` function to upload assets or WASM.
+ * 3. If changes were uploaded, submits the proposal.
+ * 4. Logs metadata (ID, status, hash).
+ * 5. Optionally commits the change if `autoCommit` is `true`.
+ *
+ * If no changes are detected during deploy, the function exits early.
+ *
+ * @param {Object} options - The deployment options.
+ * @param {ProposalType} options.proposalType - The type of change being proposed (e.g., deploy, upgrade).
+ * @param {CdnParameters} options.cdn - Parameters for interacting with the CDN and associated governance.
+ * @param {Function} options.deploy - A function that performs the actual upload and returns a `DeployResult`.
+ *   Receives the generated proposal ID as input.
+ * @param {boolean} options.autoCommit - If `true`, the function will also commit the change after submission.
+ *
+ * @returns {Promise<void>} Resolves once the deployment and optional commit are complete.
+ * Exits the process early if no changes were detected.
+ *
+ * @throws {Error} If the SHA256 hash returned from `submitProposal` is `null` or `undefined`.
+ */
+export declare const deployWithProposal: ({ proposalType, cdn, deploy, autoCommit }: {
+    proposalType: ProposalType;
+    autoCommit: boolean;
+    cdn: CdnParameters;
+    deploy: (proposalId: bigint) => Promise<DeployResult>;
+}) => Promise<void>;

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 export * from './commands/build';
 export * from './commands/deploy';
+export * from './commands/proposals';
 export * from './constants/deploy.constants';
 export type * from './types/deploy';
 export type * from './types/pkg';

package/dist/types/types/deploy.d.ts

@@ -29,3 +29,9 @@ export interface UploadFileStorage {
     description?: string;
 }
 export type UploadFile = (params: UploadFileStorage) => Promise<void>;
+export type DeployResult = {
+    result: 'deployed';
+    files: Pick<FileDetails, 'file'>[];
+} | {
+    result: 'skipped';
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junobuild/cli-tools",
-  "version": "0.1.9",
+  "version": "0.2.0-next-2025-05-23",
   "description": "A collection of tools for Juno CLIs and Plugins.",
   "author": "David Dal Busco (https://daviddalbusco.com)",
   "license": "MIT",
@@ -53,9 +53,10 @@
   ],
   "homepage": "https://juno.build",
   "peerDependencies": {
-    "@dfinity/utils": "^2",
+    "@dfinity/utils": "*",
+    "@junobuild/cdn": "*",
     "@junobuild/config": "*",
-    "esbuild": "^0.25.1"
+    "esbuild": "*"
   },
   "dependencies": {
     "file-type": "^20.4.1",
@@ -68,4 +69,4 @@
     "@types/mime-types": "^2.1.4",
     "@types/minimatch": "^5.1.2"
   }
-}
+}