slicejs-cli 4.1.1 → 4.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/client.js CHANGED
@@ -21,6 +21,7 @@ import validations from "./commands/Validations.js";
21
21
  import Print from "./commands/Print.js";
22
22
  import build from './commands/build/build.js';
23
23
  import { runGenerateTypes } from './commands/types/types.js';
24
+ import { runDocsGet, runDocsList, runDocsSearch } from './commands/docs/docs.js';
24
25
  import { cleanBundles, bundleInfo } from './commands/bundle/bundle.js';
25
26
  import {
26
27
  isLocalDelegationDisabled,
@@ -71,7 +72,10 @@ async function withNodeEnv(env, fn) {
71
72
  async function runWithVersionCheck(commandFunction, ...args) {
72
73
  try {
73
74
  const globalOpts = program.opts();
74
- const skipVersionCheck = globalOpts.noVersionCheck === false;
75
+ // Commander stores a negated `--no-version-check` option as `versionCheck`.
76
+ // Keep the old property check for compatibility with callers that construct
77
+ // program options directly.
78
+ const skipVersionCheck = globalOpts.versionCheck === false || globalOpts.noVersionCheck === false;
75
79
 
76
80
  if (!skipVersionCheck) {
77
81
  updateManager.notifyAvailableUpdates().catch(() => {});
@@ -89,6 +93,11 @@ async function runWithVersionCheck(commandFunction, ...args) {
89
93
  } catch (error) {
90
94
  Print.error(`Command execution: ${error.message}`);
91
95
  console.error(error.stack);
96
+ // A command that threw must not report success. This used to swallow the
97
+ // error and return normally, so `slice build` printed a red failure and
98
+ // still exited 0 — CI read that as a passing build and shipped it.
99
+ // process.exitCode (not process.exit) lets buffered output flush first.
100
+ process.exitCode = 1;
92
101
  return false;
93
102
  }
94
103
  }
@@ -253,7 +262,11 @@ const buildCommand = sliceClient.command("build")
253
262
  .description("Build Slice.js project for production")
254
263
  .action(async (options) => {
255
264
  await withNodeEnv('production', () => runWithVersionCheck(async () => {
256
- await build(options);
265
+ // build() reports failure by returning false (degraded files, missing
266
+ // build dependencies) rather than throwing, so it needs its own exit code.
267
+ const ok = await build(options);
268
+ if (ok === false) process.exitCode = 1;
269
+ return ok;
257
270
  }));
258
271
  });
259
272
 
@@ -278,7 +291,12 @@ buildCommand
278
291
  .option("--no-obfuscate", "Disable obfuscation (enabled by default, no prop mangling)")
279
292
  .option("--preview", "Start preview server after build")
280
293
  .option("--serve", "Start preview server without building")
281
- .option("--strict-external", "Fail the build if a node_modules dependency cannot be resolved")
294
+ // Strict is the default now. `--strict-external` is kept so existing CI
295
+ // scripts keep working — commander rejects unknown options, so dropping it
296
+ // would break them outright. It is a no-op that asks for the default.
297
+ .option("--strict-external", "Fail the build if a node_modules dependency cannot be resolved (default)")
298
+ .option("--no-strict-external", "Allow the build to continue when a node_modules dependency cannot be resolved")
299
+ .option("--allow-unoptimized", "Succeed even if some files could not be minified and shipped as-is")
282
300
  .option("--no-validate", "Skip component prop validation before building")
283
301
  .option("--sourcemap", "Emit a source map (.map) next to each minified bundle")
284
302
  .option("--hash-filenames", "Add a content hash to bundle filenames for immutable CDN caching")
@@ -513,6 +531,45 @@ skillCommand
513
531
  });
514
532
  });
515
533
 
534
+ // DOCUMENTATION COMMAND GROUP - Framework and Slice.js Components docs
535
+ const docsCommand = sliceClient.command("docs").description("Search and retrieve Slice.js documentation");
536
+
537
+ docsCommand
538
+ .command("list")
539
+ .description("List documentation from the framework, Components catalog, or both")
540
+ .option("-s, --source <source>", "Documentation source: framework, components, or all", "all")
541
+ .option("--json", "Print machine-readable JSON")
542
+ .action(async (options) => {
543
+ await runWithVersionCheck(async () => {
544
+ await runDocsList(options);
545
+ });
546
+ });
547
+
548
+ docsCommand
549
+ .command("search <query>")
550
+ .description("Search framework and Slice.js Components documentation")
551
+ .option("-s, --source <source>", "Documentation source: framework, components, or all", "all")
552
+ .option("-m, --max-results <number>", "Maximum number of results", "5")
553
+ .option("--snippets-per-doc <number>", "Maximum snippets per result", "3")
554
+ .option("--json", "Print machine-readable JSON")
555
+ .action(async (query, options) => {
556
+ await runWithVersionCheck(async () => {
557
+ await runDocsSearch(query, options);
558
+ });
559
+ });
560
+
561
+ docsCommand
562
+ .command("get <ids...>")
563
+ .description("Retrieve the authored Markdown for one or more documents")
564
+ .option("-s, --source <source>", "Documentation source: framework, components, or all", "all")
565
+ .option("--stdout", "Print only the authored Markdown")
566
+ .option("--json", "Print machine-readable JSON")
567
+ .action(async (ids, options) => {
568
+ await runWithVersionCheck(async () => {
569
+ await runDocsGet(ids, options);
570
+ });
571
+ });
572
+
516
573
  skillCommand
517
574
  .command("update")
518
575
  .description("Update the installed skill to the latest compatible version")
@@ -35,7 +35,24 @@ export default async function build(options = {}) {
35
35
  // doctor`). Definition errors fail the build so a broken component contract
36
36
  // never ships; style issues warn but don't block. Skip with --no-validate.
37
37
  if (options.validate !== false) {
38
- const { errors, warnings } = await validateComponentProps({ projectRoot: getProjectRoot(import.meta.url) });
38
+ const { errors, warnings, sourceErrors, sourceWarnings } = await validateComponentProps({ projectRoot: getProjectRoot(import.meta.url) });
39
+
40
+ // Source-level problems first: they cover every registered component,
41
+ // including ones no route reaches — which the bundler never sees at all.
42
+ if (sourceErrors.length > 0) {
43
+ Print.error(`Build blocked: ${sourceErrors.length} component source error(s) found.`);
44
+ for (const e of sourceErrors) {
45
+ Print.newLine();
46
+ Print.info(` ${e.component}: ${e.message}`);
47
+ }
48
+ Print.newLine();
49
+ Print.info('Fix the components above. These files cannot be bundled or loaded as they are.');
50
+ process.exit(1);
51
+ }
52
+
53
+ for (const w of sourceWarnings) {
54
+ Print.warning(`${w.component}: ${w.message}`);
55
+ }
39
56
 
40
57
  for (const w of warnings) {
41
58
  Print.warning(`Props: ${w.component}.${w.prop} — ${w.message}`);
@@ -3,10 +3,11 @@
3
3
  import fs from 'fs-extra';
4
4
  import path from 'path';
5
5
  import { createRequire } from 'module';
6
- import { minify as terserMinify } from 'terser';
7
6
  import { minify } from 'html-minifier-terser';
8
7
  import CleanCSS from 'clean-css';
9
8
  import Print from '../Print.js';
9
+ import { minifyJs, sourceFileOptions, componentsRegistryOptions } from '../utils/JsMinifier.js';
10
+ import { describeSyntaxError } from '../utils/SourceDiagnostics.js';
10
11
  import { getSrcPath, getDistPath, getConfigPath, getProjectRoot } from '../utils/PathHelper.js';
11
12
  import { resolvePackageManager, runScriptCommand } from '../utils/PackageManager.js';
12
13
 
@@ -43,8 +44,14 @@ async function checkBuildDependencies() {
43
44
  Print.success('Build dependencies available');
44
45
  return true;
45
46
  } catch (error) {
46
- Print.warning('Some build dependencies missing - using fallback copy mode');
47
- return true;
47
+ // This used to return true, so a build with no minifier installed reported
48
+ // success while shipping every file unoptimized. They are declared
49
+ // dependencies of the CLI — if they are missing the install is broken, and
50
+ // saying so beats producing a build nobody knows is unoptimized.
51
+ Print.error(`Build dependencies missing: ${error.message}`);
52
+ Print.info('Reinstall the project dependencies, then build again.');
53
+ Print.info('To build anyway with files copied unoptimized, pass --allow-unoptimized.');
54
+ return false;
48
55
  }
49
56
  }
50
57
 
@@ -146,8 +153,12 @@ async function copyFrameworkRuntime() {
146
153
  * Processes a complete directory
147
154
  */
148
155
  async function processDirectory(srcPath, distPath, baseSrcPath, options) {
149
- const items = await fs.readdir(srcPath);
150
-
156
+ // Sorted, not raw readdir order: readdir gives no ordering guarantee and it
157
+ // varies by filesystem, so an unstable walk would make build output and its
158
+ // logs differ between machines. Cheap insurance for reproducible builds and
159
+ // any content-hash caching built on them.
160
+ const items = (await fs.readdir(srcPath)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
161
+
151
162
  for (const item of items) {
152
163
  const srcItemPath = path.join(srcPath, item);
153
164
  const distItemPath = path.join(distPath, item);
@@ -162,6 +173,40 @@ async function processDirectory(srcPath, distPath, baseSrcPath, options) {
162
173
  }
163
174
  }
164
175
 
176
+ // Files that could not be optimized and were copied through instead. A build
177
+ // that quietly degrades is worse than one that fails: every one of the bundler
178
+ // bugs found so far shipped unoptimized output behind a red line nobody read.
179
+ // Reset per build (buildProduction) and reported before it returns.
180
+ let degradations = [];
181
+
182
+
183
+ function resetDegradations() {
184
+ degradations = [];
185
+ }
186
+
187
+
188
+ function recordDegradation(entry) {
189
+ degradations.push(entry);
190
+ }
191
+
192
+ /**
193
+ * Prints what fell back, if anything.
194
+ * @returns {boolean} true when the build was fully optimized
195
+ */
196
+ function reportDegradations() {
197
+ if (degradations.length === 0) return true;
198
+
199
+ Print.newLine();
200
+ Print.error(`${degradations.length} file(s) could not be optimized and were copied unoptimized:`);
201
+ for (const { file, reason } of degradations) {
202
+ console.log(` • ${file}: ${reason}`);
203
+ }
204
+ Print.newLine();
205
+ Print.info('These files ship as-is: unminified, comments and all. Fix the cause, or');
206
+ Print.info('pass --allow-unoptimized to accept it and let the build succeed.');
207
+ return false;
208
+ }
209
+
165
210
  /**
166
211
  * Processes an individual file
167
212
  */
@@ -223,7 +268,14 @@ async function processFile(srcFilePath, distFilePath, options) {
223
268
  Print.info(`📄 Copied: ${fileName} (${sizeKB} KB)`);
224
269
  }
225
270
  } catch (error) {
271
+ // Copying the source through keeps the build usable, but the file ships
272
+ // unoptimized — and this used to be the whole story: a red line in the
273
+ // middle of a green build. Record it so the build can report and fail on it.
226
274
  Print.error(`Processing ${fileName}: ${error.message}`);
275
+ recordDegradation({
276
+ file: path.relative(getSrcPath(import.meta.url), srcFilePath) || fileName,
277
+ reason: error.message
278
+ });
227
279
  await fs.copy(srcFilePath, distFilePath);
228
280
  }
229
281
  }
@@ -235,19 +287,7 @@ async function processComponentsFile(srcPath, distPath) {
235
287
  const content = await fs.readFile(srcPath, 'utf8');
236
288
  const originalSize = Buffer.byteLength(content, 'utf8');
237
289
 
238
- const result = await terserMinify(content, {
239
- compress: false,
240
- mangle: false,
241
- format: {
242
- comments: false,
243
- beautify: false,
244
- indent_level: 0
245
- }
246
- });
247
-
248
- if (result.error) {
249
- throw new Error(`Terser error in components.js: ${result.error}`);
250
- }
290
+ const result = await minifyJs(content, componentsRegistryOptions);
251
291
 
252
292
  await fs.writeFile(distPath, result.code, 'utf8');
253
293
 
@@ -263,67 +303,19 @@ async function processComponentsFile(srcPath, distPath) {
263
303
  async function minifyJavaScript(srcPath, distPath) {
264
304
  const content = await fs.readFile(srcPath, 'utf8');
265
305
  const originalSize = Buffer.byteLength(content, 'utf8');
266
-
267
- const result = await terserMinify(content, {
268
- compress: {
269
- drop_console: false,
270
- drop_debugger: true,
271
- pure_funcs: [],
272
- passes: 1,
273
- unused: false,
274
- side_effects: false,
275
- reduce_vars: false,
276
- collapse_vars: false
277
- },
278
- mangle: {
279
- reserved: [
280
- // Core Slice
281
- 'slice', 'Slice', 'SliceJS', 'window', 'document',
282
- // Main classes
283
- 'Controller', 'StylesManager', 'Router', 'Logger', 'Debugger',
284
- // Slice methods
285
- 'getClass', 'isProduction', 'getComponent', 'build', 'setTheme', 'attachTemplate',
286
- // Controller
287
- 'componentCategories', 'templates', 'classes', 'requestedStyles', 'activeComponents',
288
- 'registerComponent', 'registerComponentsRecursively', 'loadTemplateToComponent',
289
- 'fetchText', 'setComponentProps', 'verifyComponentIds', 'destroyComponent',
290
- // StylesManager
291
- 'componentStyles', 'themeManager', 'init', 'appendComponentStyles', 'registerComponentStyles',
292
- // Router
293
- 'routes', 'pathToRouteMap', 'activeRoute', 'navigate', 'matchRoute', 'handleRoute',
294
- 'onRouteChange', 'loadInitialRoute', 'renderRoutesComponentsInPage',
295
- // Propiedades de componentes
296
- 'sliceId', 'sliceType', 'sliceConfig', 'debuggerProps', 'parentComponent',
297
- 'value', 'customColor', 'icon', 'layout', 'view', 'items', 'columns', 'rows',
298
- 'onClickCallback', 'props',
299
- // Custom Elements
300
- 'customElements', 'define', 'HTMLElement',
301
- // Critical DOM APIs
302
- 'addEventListener', 'removeEventListener', 'querySelector', 'querySelectorAll',
303
- 'appendChild', 'removeChild', 'innerHTML', 'textContent', 'style', 'classList',
304
- // Lifecycle
305
- 'beforeMount', 'afterMount', 'beforeDestroy', 'afterDestroy',
306
- 'mount', 'unmount', 'destroy', 'update', 'start', 'stop',
307
- // Browser APIs
308
- 'fetch', 'setTimeout', 'clearTimeout', 'localStorage', 'history', 'pushState',
309
- // Exports/Imports
310
- 'default', 'export', 'import', 'from', 'await', 'async',
311
- // Nombres de componentes
312
- 'Button', 'Grid', 'Layout', 'HomePage', 'NotFound', 'Loading', 'TreeView', 'Link',
313
- 'FetchManager'
314
- ],
315
- properties: { regex: /^_/ }
316
- },
317
- format: {
318
- comments: false,
319
- beautify: false
320
- },
321
- keep_fnames: true,
322
- keep_classnames: true
323
- });
324
306
 
325
- if (result.error) {
326
- throw new Error(`Terser error: ${result.error}`);
307
+ let result;
308
+ try {
309
+ result = await minifyJs(content, sourceFileOptions);
310
+ } catch (minifyError) {
311
+ // Terser reports its own parse failures without a location and in its own
312
+ // vocabulary ("Unexpected token punc «(»"). When the file simply does not
313
+ // parse, say so against the developer's source instead.
314
+ const diagnosis = describeSyntaxError(content, srcPath);
315
+ if (!diagnosis.ok) {
316
+ throw new Error(`Syntax error at ${diagnosis.message}\nFix the source above.`);
317
+ }
318
+ throw minifyError;
327
319
  }
328
320
 
329
321
  await fs.writeFile(distPath, result.code, 'utf8');
@@ -472,7 +464,8 @@ async function analyzeBuild() {
472
464
  export default async function buildProduction(options = {}) {
473
465
  const startTime = Date.now();
474
466
  const packageManager = resolvePackageManager(getProjectRoot(import.meta.url)).name;
475
-
467
+ resetDegradations();
468
+
476
469
  try {
477
470
  Print.title('🔨 Building Slice.js project for production...');
478
471
  Print.newLine();
@@ -511,8 +504,14 @@ export default async function buildProduction(options = {}) {
511
504
  await createOptimizedBundle();
512
505
  await generateBuildStats(srcDir, distDir);
513
506
 
507
+ const fullyOptimized = reportDegradations();
508
+ if (!fullyOptimized && !options.allowUnoptimized) {
509
+ Print.error('Build failed: not every file could be optimized (see above).');
510
+ return false;
511
+ }
512
+
514
513
  const buildTime = ((Date.now() - startTime) / 1000).toFixed(1);
515
-
514
+
516
515
  Print.newLine();
517
516
  Print.success(`✨ Slice.js production build completed in ${buildTime}s`);
518
517
  Print.info('Your optimized project is ready in the /dist directory');
@@ -585,7 +584,9 @@ export async function buildCommand(options = {}) {
585
584
  const config = loadConfig();
586
585
  const defaultPort = config?.server?.port || 3001;
587
586
 
588
- if (!await checkBuildDependencies()) {
587
+ // Missing minifiers are fatal unless the caller explicitly accepts an
588
+ // unoptimized build.
589
+ if (!await checkBuildDependencies() && !options.allowUnoptimized) {
589
590
  return false;
590
591
  }
591
592