slicejs-cli 4.0.0 → 4.1.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/README.md CHANGED
@@ -111,9 +111,41 @@ allowBuilds:
111
111
  | `slice get <component>` | Install components from the official registry |
112
112
  | `slice browse` | Browse available components |
113
113
  | `slice component create` | Create a local component |
114
+ | `slice skill add` | Install the Slice.js Claude Code skill into `.claude/skills/` |
114
115
  | `slice doctor` | Run project diagnostics |
115
116
  | `slice postinstall` | Configure npm scripts (alternative to postinstall) |
116
117
 
118
+ ## Claude Code skill (`slice skill`)
119
+
120
+ Installs the `slice-js-developer` skill — the guide Claude Code uses to build Slice.js
121
+ apps correctly — into your project by fetching it from the official docs repo
122
+ (`VKneider/slicejs_docs`), which is the single source of truth. A `manifest.json`
123
+ there pins the skill version, its framework-compatibility range, and the exact file
124
+ list, so the install never drifts.
125
+
126
+ | Command | Description |
127
+ |---------|-------------|
128
+ | `slice skill add` | Install the skill (prompts before overwriting an existing copy; `--force` skips the prompt) |
129
+ | `slice skill update` | Update the installed skill to the latest compatible version |
130
+ | `slice skill status` | Show the installed version vs. the latest available |
131
+
132
+ The skill is written to **`.claude/skills/slice-js-developer/`** at the **project
133
+ root** — inside Claude Code's standard skills path, not a loose folder next to `src/`:
134
+
135
+ ```
136
+ my-app/
137
+ ├── .claude/skills/slice-js-developer/ ← installed here
138
+ ├── api/
139
+ ├── src/ ← untouched
140
+ └── package.json
141
+ ```
142
+
143
+ > **Run `slice skill` commands from the project root.** All three subcommands
144
+ > (`add`, `update`, `status`) resolve the target from `INIT_CWD` / the current working
145
+ > directory, so running from a subfolder can place `.claude/` somewhere unexpected.
146
+ > The install path itself is configurable via the `installPath` field in the docs
147
+ > repo's `manifest.json`. After installing, reload Claude Code to pick up the skill.
148
+
117
149
  ## Postinstall Scripts
118
150
 
119
151
  When you install `slicejs-cli`, the `postinstall` script automatically configures `slice:*` npm scripts in your `package.json`:
package/client.js CHANGED
@@ -6,6 +6,7 @@ import createComponent from "./commands/createComponent/createComponent.js";
6
6
  import listComponents from "./commands/listComponents/listComponents.js";
7
7
  import deleteComponent from "./commands/deleteComponent/deleteComponent.js";
8
8
  import getComponent, { listComponents as listRemoteComponents, syncComponents } from "./commands/getComponent/getComponent.js";
9
+ import { addSkill, statusSkill, updateSkill } from "./commands/skill/skill.js";
9
10
  import startServer from "./commands/startServer/startServer.js";
10
11
  import runDiagnostics from "./commands/doctor/doctor.js";
11
12
  import versionChecker from "./commands/utils/VersionChecker.js";
@@ -498,6 +499,38 @@ componentCommand
498
499
  // REGISTRY COMMAND GROUP - For component registry operations
499
500
  const registryCommand = sliceClient.command("registry").alias("reg").description("Manage components from official Slice.js repository");
500
501
 
502
+ // SKILL COMMAND GROUP - Claude Code skill fetched from the docs repo
503
+ const skillCommand = sliceClient.command("skill").description("Manage the Slice.js Claude Code skill (fetched from the official docs repo)");
504
+
505
+ skillCommand
506
+ .command("add")
507
+ .alias("install")
508
+ .description("Install the slice-js-developer skill into .claude/skills/")
509
+ .option("-f, --force", "Overwrite an already-installed skill without prompting")
510
+ .action(async (options) => {
511
+ await runWithVersionCheck(async () => {
512
+ await addSkill({ force: options.force });
513
+ });
514
+ });
515
+
516
+ skillCommand
517
+ .command("update")
518
+ .description("Update the installed skill to the latest compatible version")
519
+ .action(async () => {
520
+ await runWithVersionCheck(async () => {
521
+ await updateSkill();
522
+ });
523
+ });
524
+
525
+ skillCommand
526
+ .command("status")
527
+ .description("Show installed vs latest skill version")
528
+ .action(async () => {
529
+ await runWithVersionCheck(async () => {
530
+ await statusSkill();
531
+ });
532
+ });
533
+
501
534
  // TYPES COMMAND GROUP - TypeScript declarations from static props
502
535
  const typesCommand = sliceClient.command("types").description("Generate TypeScript declarations from component static props");
503
536
 
@@ -706,14 +739,16 @@ Common Usage Examples:
706
739
  slice list - List all local components
707
740
  slice doctor - Run project diagnostics
708
741
  slice types generate - Generate TypeScript typings for slice.build
742
+ slice skill add - Install the Slice.js Claude Code skill
709
743
  slice postinstall - Configure npm scripts in package.json
710
744
 
711
745
  Command Categories:
712
746
  • init, dev, start - Project lifecycle (development only)
713
- • get, browse, sync, list - Quick shortcuts
747
+ • get, browse, sync, list - Quick shortcuts
714
748
  • component <cmd> - Local component management
715
749
  • registry <cmd> - Official repository operations
716
750
  • types generate - Type declarations from static props
751
+ • skill <cmd> - Claude Code skill (add / update / status)
717
752
  • version, doctor, setup - Maintenance commands
718
753
 
719
754
  Development Workflow:
@@ -0,0 +1,236 @@
1
+ // commands/skill/skill.js
2
+ //
3
+ // Installs the Slice.js Claude Code skill (slice-js-developer) into a project's
4
+ // .claude/skills/ folder by fetching it from the docs repo. The docs repo is the
5
+ // single source of truth; a manifest.json there lists the version, the framework
6
+ // compatibility range, and the exact file list to copy — so nothing drifts.
7
+
8
+ import fs from "fs-extra";
9
+ import path from "path";
10
+ import inquirer from "inquirer";
11
+ import ora from "ora";
12
+ import Print from "../Print.js";
13
+ import { getProjectRoot } from "../utils/PathHelper.js";
14
+ import { fetchWithRetry, runConcurrent } from "../getComponent/getComponent.js";
15
+
16
+ // Canonical home: VKneider/slicejs_docs → /skill. The MCP already sources docs
17
+ // from this same repo, keeping the skill co-located with what it distills.
18
+ // Override with SLICE_SKILL_REPO_BASE_URL (a fork, a branch, or a local server for testing).
19
+ const SKILL_REPO_BASE_URL =
20
+ process.env.SLICE_SKILL_REPO_BASE_URL ||
21
+ "https://raw.githubusercontent.com/VKneider/slicejs_docs/master/skill";
22
+ const MANIFEST_URL = `${SKILL_REPO_BASE_URL}/manifest.json`;
23
+
24
+ async function fetchManifest() {
25
+ const raw = await fetchWithRetry(MANIFEST_URL, 3, 500, false);
26
+ let manifest;
27
+ try {
28
+ manifest = JSON.parse(raw);
29
+ } catch {
30
+ throw new Error("skill manifest is not valid JSON");
31
+ }
32
+ if (!manifest.name || !manifest.version || !Array.isArray(manifest.files) || !manifest.installPath) {
33
+ throw new Error("skill manifest is missing required fields (name, version, installPath, files)");
34
+ }
35
+ // The manifest is fetched over the network and drives where files get written.
36
+ // Never let it escape the install directory: reject absolute paths and any ".."
37
+ // segment in installPath or in a file entry (path-traversal hardening).
38
+ const unsafe = (p) =>
39
+ typeof p !== "string" || p.length === 0 || path.isAbsolute(p) || p.split(/[\\/]+/).includes("..");
40
+ if (unsafe(manifest.installPath)) {
41
+ throw new Error(`unsafe installPath in manifest: "${manifest.installPath}"`);
42
+ }
43
+ const badFile = manifest.files.find(unsafe);
44
+ if (badFile !== undefined) {
45
+ throw new Error(`unsafe file path in manifest: "${badFile}"`);
46
+ }
47
+ return manifest;
48
+ }
49
+
50
+ // The skill's own VERSION file is the source of truth for what's installed.
51
+ function readLocalVersion(installDir) {
52
+ const versionPath = path.join(installDir, "VERSION");
53
+ if (!fs.pathExistsSync(versionPath)) return null;
54
+ const raw = fs.readFileSync(versionPath, "utf8");
55
+ const line = raw.split("\n").find((l) => l.trim().toLowerCase().startsWith("version:"));
56
+ return line ? line.slice(line.indexOf(":") + 1).trim() : null;
57
+ }
58
+
59
+ // First integer in a version-ish string ("4.0.1" / "^4.0.x" → 4).
60
+ function majorOf(value) {
61
+ const m = String(value || "").match(/(\d+)/);
62
+ return m ? parseInt(m[1], 10) : null;
63
+ }
64
+
65
+ // Best-effort read of the installed framework version (real installed wins over
66
+ // a declared range). Returns null when it can't be determined.
67
+ function detectFrameworkVersion(projectRoot) {
68
+ const installed = path.join(projectRoot, "node_modules", "slicejs-web-framework", "package.json");
69
+ if (fs.pathExistsSync(installed)) {
70
+ try {
71
+ return JSON.parse(fs.readFileSync(installed, "utf8")).version;
72
+ } catch {
73
+ /* fall through */
74
+ }
75
+ }
76
+ const projectPkg = path.join(projectRoot, "package.json");
77
+ if (fs.pathExistsSync(projectPkg)) {
78
+ try {
79
+ const pkg = JSON.parse(fs.readFileSync(projectPkg, "utf8"));
80
+ return (pkg.dependencies && pkg.dependencies["slicejs-web-framework"]) ||
81
+ (pkg.devDependencies && pkg.devDependencies["slicejs-web-framework"]) ||
82
+ null;
83
+ } catch {
84
+ /* fall through */
85
+ }
86
+ }
87
+ return null;
88
+ }
89
+
90
+ // Soft compatibility gate: warns on a major mismatch, never blocks.
91
+ function reportCompatibility(manifest, projectRoot) {
92
+ const fw = detectFrameworkVersion(projectRoot);
93
+ if (!fw) {
94
+ Print.info("Could not detect slicejs-web-framework in this project — skipping compatibility check.");
95
+ return;
96
+ }
97
+ const targetMajor = majorOf(manifest.targets);
98
+ const fwMajor = majorOf(fw);
99
+ if (targetMajor != null && fwMajor != null && targetMajor !== fwMajor) {
100
+ Print.warning(
101
+ `Skill v${manifest.version} targets ${manifest.targets}, but this project uses slicejs-web-framework@${fw}. ` +
102
+ `Installing anyway — verify the guidance matches your framework version.`
103
+ );
104
+ } else {
105
+ Print.info(`Compatible with slicejs-web-framework@${fw} (targets ${manifest.targets}).`);
106
+ }
107
+ }
108
+
109
+ async function downloadSkillFiles(manifest, installDir) {
110
+ const total = manifest.files.length;
111
+ let done = 0;
112
+ const failed = [];
113
+ const spinner = ora(`Downloading skill 0/${total}`).start();
114
+ const worker = async (file) => {
115
+ const url = `${SKILL_REPO_BASE_URL}/${manifest.name}/${file}`;
116
+ const dest = path.join(installDir, file);
117
+ try {
118
+ const content = await fetchWithRetry(url, 3, 500, false);
119
+ await fs.ensureDir(path.dirname(dest));
120
+ await fs.writeFile(dest, content, "utf8");
121
+ } catch {
122
+ failed.push(file);
123
+ } finally {
124
+ done += 1;
125
+ spinner.text = `Downloading skill ${done}/${total}`;
126
+ }
127
+ };
128
+ await runConcurrent(manifest.files, worker, 4);
129
+ spinner.stop();
130
+ return failed;
131
+ }
132
+
133
+ // Install (or reinstall) the skill. `force` skips the overwrite prompt.
134
+ async function addSkill(options = {}) {
135
+ const projectRoot = getProjectRoot(import.meta.url);
136
+
137
+ let manifest;
138
+ try {
139
+ manifest = await fetchManifest();
140
+ } catch (error) {
141
+ Print.error(`Could not load the skill manifest from the docs repository: ${error.message}`);
142
+ Print.info("Check your internet connection and try again.");
143
+ return false;
144
+ }
145
+
146
+ const installDir = path.join(projectRoot, manifest.installPath);
147
+ const localVersion = readLocalVersion(installDir);
148
+
149
+ if (await fs.pathExists(installDir) && !options.force) {
150
+ if (localVersion === manifest.version) {
151
+ Print.info(`Skill '${manifest.name}' v${manifest.version} is already installed and up to date.`);
152
+ Print.commandExample("Reinstall anyway", "slice skill add --force");
153
+ return true;
154
+ }
155
+ const { overwrite } = await inquirer.prompt([
156
+ {
157
+ type: "confirm",
158
+ name: "overwrite",
159
+ message: localVersion
160
+ ? `Skill '${manifest.name}' v${localVersion} is installed; replace it with v${manifest.version}?`
161
+ : `'${manifest.installPath}' already exists; overwrite it with skill v${manifest.version}?`,
162
+ default: true,
163
+ },
164
+ ]);
165
+ if (!overwrite) {
166
+ Print.info("Installation cancelled.");
167
+ return false;
168
+ }
169
+ }
170
+
171
+ reportCompatibility(manifest, projectRoot);
172
+
173
+ const failed = await downloadSkillFiles(manifest, installDir);
174
+ if (failed.length === manifest.files.length) {
175
+ Print.error("Failed to download the skill — no files were written.");
176
+ return false;
177
+ }
178
+ if (failed.length > 0) {
179
+ Print.warning(`Some files couldn't be downloaded: ${failed.join(", ")}`);
180
+ }
181
+
182
+ Print.success(`Skill '${manifest.name}' v${manifest.version} installed at ${manifest.installPath}/`);
183
+ Print.info("Reload Claude Code (or restart the session) to pick up the skill.");
184
+ return true;
185
+ }
186
+
187
+ // Update = install the latest, replacing an existing copy without prompting.
188
+ async function updateSkill(options = {}) {
189
+ const projectRoot = getProjectRoot(import.meta.url);
190
+ const installDir = (() => {
191
+ // installPath comes from the manifest; peek at the default so we can report
192
+ // the current version before fetching. Falls back gracefully if absent.
193
+ return path.join(projectRoot, ".claude", "skills", "slice-js-developer");
194
+ })();
195
+ const before = readLocalVersion(installDir);
196
+ if (before) Print.info(`Currently installed: v${before}`);
197
+ return addSkill({ ...options, force: true });
198
+ }
199
+
200
+ // Show installed vs latest, and whether an update is available.
201
+ async function statusSkill() {
202
+ const projectRoot = getProjectRoot(import.meta.url);
203
+
204
+ let manifest;
205
+ try {
206
+ manifest = await fetchManifest();
207
+ } catch (error) {
208
+ Print.error(`Could not load the skill manifest from the docs repository: ${error.message}`);
209
+ Print.info("Check your internet connection and try again.");
210
+ return false;
211
+ }
212
+
213
+ const installDir = path.join(projectRoot, manifest.installPath);
214
+ const localVersion = readLocalVersion(installDir);
215
+
216
+ Print.title("Slice.js Claude Code skill");
217
+ console.log(` name: ${manifest.name}`);
218
+ console.log(` latest: v${manifest.version} (targets ${manifest.targets})`);
219
+ console.log(` installed: ${localVersion ? "v" + localVersion : "not installed"}`);
220
+ console.log(` files: ${manifest.files.length}`);
221
+ console.log(` path: ${manifest.installPath}/`);
222
+ Print.newLine();
223
+
224
+ if (!localVersion) {
225
+ Print.commandExample("Install the skill", "slice skill add");
226
+ } else if (localVersion !== manifest.version) {
227
+ Print.info(`Update available: v${localVersion} → v${manifest.version}`);
228
+ Print.commandExample("Update", "slice skill update");
229
+ } else {
230
+ Print.success("Installed skill is up to date.");
231
+ }
232
+ return true;
233
+ }
234
+
235
+ export default addSkill;
236
+ export { addSkill, updateSkill, statusSkill };
@@ -848,7 +848,8 @@ export default class BundleGenerator {
848
848
  const routeFile = await this.createBundleFile(
849
849
  bundle.components,
850
850
  'route',
851
- routeIdentifier
851
+ routeIdentifier,
852
+ routeKey
852
853
  );
853
854
  bundle.file = routeFile.file;
854
855
  bundle.hash = routeFile.hash;
@@ -976,7 +977,9 @@ export default class BundleGenerator {
976
977
  const measuredSize = entry?.external
977
978
  ? Buffer.byteLength(entry?.content || '', 'utf-8')
978
979
  : Buffer.byteLength(
979
- this.transformDependencyContent(entry?.content || '', '__sliceVendorSharedProbe', dependencyName),
980
+ // Size probe only — nothing here is emitted, so it must stay quiet
981
+ // rather than double-report warnings the real emit already covers.
982
+ this.transformDependencyContent(entry?.content || '', '__sliceVendorSharedProbe', dependencyName, { silent: true }),
980
983
  'utf-8'
981
984
  );
982
985
  if (measuredSize < this.config.minVendorSharedTransformedSize) continue;
@@ -1033,8 +1036,14 @@ export default class BundleGenerator {
1033
1036
  /**
1034
1037
  * Creates a bundle file
1035
1038
  */
1036
- async createBundleFile(components, type, routePath) {
1037
- const routeKey = routePath ? this.routeToFileName(routePath) : 'critical';
1039
+ async createBundleFile(components, type, routePath, bundleKey = null) {
1040
+ // The key — not the route path — names the file. Size-split parts of one
1041
+ // route (`playground--p1`, `--p2`) share a `path`, so deriving the name from
1042
+ // the path makes every part collide on `slice-bundle.playground.js` and the
1043
+ // last one written wins, silently dropping the other parts' components.
1044
+ const routeKey = bundleKey
1045
+ ? this.routeToFileName(bundleKey)
1046
+ : (routePath ? this.routeToFileName(routePath) : 'critical');
1038
1047
  const baseFileName = `slice-bundle.${routeKey}.js`;
1039
1048
 
1040
1049
  const bundleContent = await this.generateBundleContent(
@@ -1578,7 +1587,7 @@ export default class BundleGenerator {
1578
1587
  });
1579
1588
  }
1580
1589
 
1581
- return this.generateBundleFileContent(fileName, type, this.sortComponentsByName(bundleComponents), routePath);
1590
+ return this.generateBundleFileContent(fileName, type, this.sortComponentsByName(bundleComponents), routePath, bundleKey);
1582
1591
  }
1583
1592
 
1584
1593
  classFactoryName(componentName) {
@@ -1593,13 +1602,19 @@ export default class BundleGenerator {
1593
1602
  .join('\n');
1594
1603
  }
1595
1604
 
1596
- generateBundleFileContent(fileName, type, components, routePath = null) {
1605
+ generateBundleFileContent(fileName, type, components, routePath = null, bundleKeyOverride = null) {
1597
1606
  const uniqueComponents = this.dedupeComponentsByName(components || []);
1607
+ // `bundleKeyOverride` carries the split-aware key (`playground--p1`) so the
1608
+ // emitted META matches the key the runtime looks up in `routeBundles`.
1598
1609
  const bundleKey = type === 'critical'
1599
1610
  ? 'critical'
1600
1611
  : type === 'framework'
1601
1612
  ? 'framework'
1602
- : this.routeToFileName(routePath || fileName.replace('slice-bundle.', '').replace('.js', ''));
1613
+ : this.routeToFileName(
1614
+ bundleKeyOverride
1615
+ || routePath
1616
+ || fileName.replace('slice-bundle.', '').replace('.js', '')
1617
+ );
1603
1618
 
1604
1619
  const dependencyModules = this.collectDependencyModulesFromComponents(uniqueComponents);
1605
1620
  const isRouteBundle = type === 'route';
@@ -1745,11 +1760,21 @@ export default class BundleGenerator {
1745
1760
  .filter((mi) => mi.specifier && mi.depName)
1746
1761
  .map((mi) => [mi.specifier, mi.depName])
1747
1762
  );
1763
+ // Every specifier this module's imports were analyzed under — bare ones by
1764
+ // name, relative ones by the specifier as written. Each has its module
1765
+ // emitted in this block and its bindings re-created below, so stripping the
1766
+ // original statement loses nothing and must not warn.
1767
+ const handledSpecifiers = new Set(
1768
+ (module.moduleImports || [])
1769
+ .map((mi) => (mi.external ? mi.depName : mi.specifier))
1770
+ .filter((specifier) => typeof specifier === 'string')
1771
+ );
1748
1772
  const transformedContent = this.transformDependencyContent(module.content, '__sliceExports', module.name, {
1749
1773
  // A re-export inside this helper must resolve its source through the same
1750
1774
  // shared resolver the bundle uses, since the source may live in vendor-shared.
1751
1775
  preferShared: !!options.includeSharedResolver,
1752
- specifierToKey
1776
+ specifierToKey,
1777
+ handledSpecifiers
1753
1778
  });
1754
1779
  // Bind this module's own (transitive) imports inside its IIFE — they were
1755
1780
  // registered by earlier modules in the topological order.
@@ -2234,12 +2259,21 @@ if (window.slice && window.slice.controller) {
2234
2259
  const specifierToKey = options.specifierToKey || null;
2235
2260
 
2236
2261
  if (node.type === 'ImportDeclaration') {
2237
- // Transitive imports of a bundled dependency cannot be resolved at
2238
- // runtime; strip them so they never leak into the emitted bundle.
2239
- console.warn(this.buildImportWarningMessage(
2240
- `Warning: Stripping unsupported import inside bundled dependency: ${node.source?.value}`,
2241
- moduleName
2242
- ));
2262
+ // An import listed in `handledSpecifiers` is not dropped: the caller
2263
+ // re-emits it as an IIFE-scoped binding (buildDependencyBindings), and
2264
+ // removing the original statement is the second half of that rewrite.
2265
+ // Only an import nothing rebinds is actually lost — warn for that one.
2266
+ const specifier = node.source?.value;
2267
+ const handled = options.handledSpecifiers instanceof Set
2268
+ && typeof specifier === 'string'
2269
+ && options.handledSpecifiers.has(specifier);
2270
+
2271
+ if (!handled && !options.silent) {
2272
+ console.warn(this.buildImportWarningMessage(
2273
+ `Warning: Stripping unsupported import inside bundled dependency: ${specifier}`,
2274
+ moduleName
2275
+ ));
2276
+ }
2243
2277
  return '';
2244
2278
  }
2245
2279
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "slicejs-cli",
3
- "version": "4.0.0",
3
+ "version": "4.1.0",
4
4
  "description": "Command client for developing web applications with Slice.js framework",
5
5
  "main": "client.js",
6
6
  "bin": {